Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/troubleshooting.rst @ 991:1316bc62b5d5
migration to UCLouvain servers
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Tue, 21 Nov 2023 21:09:02 +0100 |
| parents | 46e2941b57dd |
| children | 17bf6fafb884 |
| rev | line source |
|---|---|
| 0 | 1 .. _troubleshooting: |
| 2 | |
| 3 Troubleshooting | |
| 4 =============== | |
| 5 | |
| 16 | 6 As a general rule, when you encounter an issue, always make sure that |
| 7 you use the `most recent version | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
8 <https://www.orthanc-server.com/download.php>`__ of Orthanc. |
| 16 | 9 |
|
984
46e2941b57dd
replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents:
903
diff
changeset
|
10 Also make a search on the `Orthanc Users discussion forum |
|
46e2941b57dd
replace link to google users group by link to discourse
Alain Mazy <am@osimis.io>
parents:
903
diff
changeset
|
11 <https://discourse.orthanc-server.org>`__, and make a |
| 16 | 12 search in the present Orthanc Book (there is a search field at the top |
| 13 of this page). Your issue might indeed have already been discussed in | |
| 14 the past or in the FAQ. | |
| 15 | |
| 108 | 16 Startup |
| 17 ------- | |
| 654 | 18 |
| 108 | 19 * If **Orthanc fails to start** with the error "**The TCP port of the DICOM |
| 20 server is privileged or already in use**", this means another software is | |
| 21 already using the port Orthanc is trying to use. Usually, this means | |
| 22 that an other instance of Orthanc is running. However, note that, by default, | |
| 23 Orthanc uses port 4242 which might also be used by other software like | |
| 24 a `Juniper VPN client <https://www.file.net/process/dsncservice.exe.html>`__. | |
| 25 To determine which other process is using the port: | |
| 26 | |
| 27 On Windows, you may use the `Resource Monitor <https://en.wikipedia.org/wiki/Resource_Monitor>`__. | |
| 28 In the `Network` tab, check the `Listening Ports`. | |
| 29 | |
| 30 On Linux, you may use this command line: ``sudo ss --tcp --listen --numeric --processes``. | |
| 31 | |
| 32 Starting with version 1.3.0, the check at Orthanc startup is more robust | |
| 33 (it also checks for UDP socket using the same port) and Orthanc 1.3.0 might | |
| 34 display error messages that where not displayed by previous versions. | |
| 16 | 35 |
|
754
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
36 * If Orthanc **does not start anymore after a hard shutdown** and if |
| 755 | 37 you use the :ref:`Orthanc Web viewer plugin <webviewer>`, this might |
|
754
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
38 reflect a corruption in the cache of the Web viewer. In such a case, |
|
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
39 it is safe to remove the folder that contains the cache. By default, |
|
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
40 this folder is called ``OrthancStorage/WebViewerCache/`` |
|
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
41 (cf. :ref:`configuration option <configuration>` ``CachePath`` in |
|
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
42 the ``WebViewer`` section). Of course, don't remove the folder |
|
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
43 ``OrthancStorage/``, as it contains the DICOM files. |
|
1e6ead2a9901
troubleshooting web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
659
diff
changeset
|
44 |
| 654 | 45 |
| 46 Validating DICOM files | |
| 47 ---------------------- | |
| 48 | |
| 49 * Invalid DICOM files are often encountered in practice. Such files | |
| 50 can cause failures in Orthanc, or can prevent DICOM network | |
| 51 transfers. You can validate DICOM files by using the ``dciodvfy`` | |
| 52 command-line tool (cf. `its documentation | |
| 53 <http://dclunie.com/dicom3tools/dciodvfy.html>`__) from the | |
| 54 `dicom3tools <https://www.dclunie.com/dicom3tools.html>`__ project | |
| 55 by David Clunie. | |
| 56 | |
| 57 The core team of Orthanc will **only provide support for DICOM files | |
| 58 that are reported as valid** by ``dciodvfy``. | |
| 59 | |
|
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
60 * Side-note: The default transfer syntax of DICOM is Little Endian |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
61 Implicit (``1.2.840.10008.1.2``). For DICOM files that include |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
62 private tags, **we recommend using Little Endian Explicit** |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
63 (``1.2.840.10008.1.2.1``) instead Little Endian Implicit whenever |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
64 possible. Instead, in Little Endian Explicit, each DICOM tag has an |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
65 explicit declaration of its value representation (type), which |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
66 contrasts with Little Endian Implicit that necessitates to configure |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
67 the dictionary of private tags to be properly handled in some |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
68 operations (cf. the ``Dictionary`` :ref:`configuration option |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
69 <configuration>`). |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
70 |
| 654 | 71 |
| 16 | 72 Orthanc Explorer |
| 73 ---------------- | |
| 74 | |
| 0 | 75 * **I cannot login to Orthanc Explorer**: For security reasons, access |
| 76 to Orthanc from remote hosts is disabled by default. Only the | |
| 77 localhost is allowed to access Orthanc. You have to set the | |
| 78 ``RemoteAccessAllowed`` option in the :ref:`configuration file | |
| 79 <configuration>` to ``true``. It is then strongly advised to set | |
| 80 ``AuthenticationEnabled`` to ``true`` and to add a user to the | |
| 81 ``RegisteredUsers`` option, also in the configuration file. | |
| 16 | 82 |
| 83 | |
| 84 Performance issues | |
| 85 ------------------ | |
| 86 | |
| 41 | 87 * **Run-time debug assertions**: If performance is important to you, |
| 88 make sure to add the option ``-DCMAKE_BUILD_TYPE=Release`` when | |
| 89 invoking ``cmake`` while :ref:`compiling Orthanc | |
| 90 <compiling>`. Indeed, by default, `run-time debug assertions | |
| 91 <https://en.wikipedia.org/wiki/Assertion_(software_development)#Assertions_for_run-time_checking>`_ | |
| 92 are enabled, which can seriously impact performance, especially if | |
| 93 your Orthanc server stores a lot of DICOM instances. | |
| 94 | |
| 95 Note that the `official Docker images | |
| 96 <https://github.com/jodogne/OrthancDocker>`__ of Orthanc <= 1.0.0 | |
| 97 were not compiled in ``Release`` mode. As a consequence, to improve | |
| 98 performance, make sure to use either the mainline version of the | |
| 43 | 99 container (run ``docker pull jodogne/orthanc`` to ensure you use the |
| 100 most recent version of the mainline), or versions more recent than | |
| 122 | 101 ``jodogne/orthanc:1.1.0``. |
| 41 | 102 |
| 44 | 103 * **Orthanc slows down if storing many files**: The default database |
| 104 engine that is built in Orthanc is `SQLite | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
105 <https://www.sqlite.org/index.html>`__. As SQLite is above all a |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
106 lightweight database engine, it is not designed to `store very large |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
107 datasets <https://www.sqlite.org/whentouse.html>`__. If you are sure |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
108 that you have properly disabled run-time debug assertions |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
109 (cf. above), but still experience degradation in performance over |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
110 time, you should seriously consider switching to a more scalable |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
111 database engine. To this end, you can notably check out the |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
112 :ref:`official PostgreSQL plugin <postgresql>`. |
| 44 | 113 |
| 114 As a rule of thumb, the performance of the default SQLite engine | |
| 115 built in Orthanc should run fine up to about 50,000 DICOM instances. | |
| 188 | 116 However, we have seen Orthanc running fairly well with more than 2 |
| 117 millions of instances. This limit really depends upon your | |
| 118 application, and upon the patterns of access to the database. | |
| 119 | |
| 186 | 120 Also check out the section about the :ref:`scalability`. |
| 44 | 121 |
| 122 | |
| 18 | 123 * **Orthanc Explorer is slow under Windows on the localhost**: |
| 124 | |
| 125 - Favor ``127.0.0.1`` instead of ``localhost`` when specifying the | |
| 126 network address of a server. Users have reported that this minor | |
| 127 change `can massively improve performance | |
| 128 <https://groups.google.com/d/msg/orthanc-users/tTe28zR0nGk/Lvs0STJLAgAJ>`__ | |
| 129 on Windows. Starting with Orthanc 1.0.1, the samples from the | |
| 130 source distribution have been adapted in this way. | |
| 131 | |
| 132 - As an alternative, you can disable IPv6 support. This is a | |
| 133 Windows-specific problem that is discussed `here | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
134 <https://superuser.com/questions/43823/google-chrome-is-slow-to-localhost>`__ |
| 18 | 135 and `here |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
136 <https://stackoverflow.com/questions/1726585/firefox-and-chrome-slow-on-localhost-known-fix-doesnt-work-on-windows-7>`__. |
| 16 | 137 |
| 42 | 138 * If you experience **slow DICOM transfers under GNU/Linux**, please |
| 139 read the `following bug report | |
| 16 | 140 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=785400>`__. This |
| 42 | 141 issue does *not* affect all the versions of GNU/Linux. A patch to |
| 142 this issue is shipped with the Orthanc source code. In order to take | |
| 143 advantage of this patch, you need to statically link Orthanc against | |
| 144 DCMTK by using the ``-DUSE_SYSTEM_DCMTK=OFF`` flag `when invoking | |
| 145 CMake | |
|
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
984
diff
changeset
|
146 <https://orthanc.uclouvain.be/hg/orthanc/file/default/LinuxCompilation.txt>`__. |
| 16 | 147 |
| 654 | 148 |
| 149 Checking integrity of the storage area | |
| 150 -------------------------------------- | |
| 151 | |
| 152 .. highlight:: bash | |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
153 |
| 654 | 154 Orthanc stores, in its database, an `MD5 hash |
| 155 <https://en.wikipedia.org/wiki/MD5>`_ of the files stored in its | |
|
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
156 :ref:`storage area <orthanc-storage>` (which notably includes the |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
157 DICOM files), provided that the ``StoreMD5ForAttachments`` |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
158 configuration option is set to ``true``. |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
159 |
|
656
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
160 This MD5 corresponds to the hash of the files in memory, before they |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
161 are written to the disk by Orthanc. This information is safely stored |
|
55a93745e874
use little endian explicit instead of implicit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
654
diff
changeset
|
162 inside the database for any incoming file attachment. |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
163 |
| 654 | 164 It is possible to ask Orthanc to check by itself whether some attachment |
| 165 file was corrupted (i.e. to check whether the MD5 hash stored in the | |
| 166 database corresponds to the hash of the file on the disk):: | |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
167 |
| 654 | 168 $ curl -X POST http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/verify-md5 -d '' |
|
193
99ba212989cc
Added entry related to MD5 integrity file checking
bgo-osimis
parents:
188
diff
changeset
|
169 |
| 654 | 170 This MD5 may be different if errors occurred while the DICOM file was |
| 171 initially written to the storage, or if the file contents were | |
| 172 tampered with afterwards. | |
| 173 | |
| 174 You can retrieve the stored MD5 hash of a DICOM instance as follows:: | |
| 175 | |
| 176 $ curl http://localhost:8042/instances/f257b066-f3992cc4-ca6a5e5f-3f8dcf3a-d4958939/attachments/dicom/md5 | |
| 16 | 177 |
| 178 Windows-specific issues | |
| 179 ----------------------- | |
| 180 | |
| 0 | 181 * Under Windows, Orthanc creates the "OrthancStorage" folder, and |
| 182 crashes with the error "**SQLite: Unable to open the database**": | |
| 183 Your directory name is either too long, or it contains special | |
| 184 characters. Please try and run Orthanc in a folder with a simple | |
| 185 name such as ``C:\Orthanc``. | |
| 55 | 186 |
|
903
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
187 * If you run Orthanc as a Windows service, and if you want to store |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
188 the Orthanc database (or the :ref:`Orthanc Web Viewer plugin |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
189 <webviewer>`) onto a shared network drive, you might encounter an |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
190 error ``boost::filesystem::status: The specified server cannot |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
191 perform the requested operation``. This probably means that the |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
192 ``SYSTEM`` account is not allowed to access the **mapped network |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
193 drive**. The easiest approach to this end consists in configuring |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
194 the Windows service to **run as user** (instead of the default |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
195 ``SYSTEM`` account), `as explained in this thread |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
196 <https://groups.google.com/g/orthanc-users/c/axrJfgA-Enk/m/Zeg3iUPOAwAJ>`__ |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
197 on the Orthanc Users forum (cf. `additional reference |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
198 <https://docs.microfocus.com/SM/9.61/Hybrid/Content/serversetup/tasks/configure_the_service_manager_service_to_run_as_a_windows_user.htm>`__ |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
199 elsewhere on Internet). |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
200 |
| 55 | 201 * If **Orthanc crashes when handling one large DICOM file**, this most |
| 202 probably indicates a memory allocation error. Indeed, the `official | |
| 203 Windows binaries | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
204 <https://www.orthanc-server.com/download-windows.php>`__ are compiled |
| 55 | 205 using a 32bit compiler. As a consequence, Orthanc only has access to |
| 206 less than 4GB of RAM. If this is an important limitation for you, | |
| 207 precompiled command-line versions of Orthanc for Windows 64bit are | |
| 208 available courtesy of `Osimis | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
193
diff
changeset
|
209 <https://www.osimis.io/en/download.html>`__. |
| 659 | 210 |
| 211 * Avoid installing Orthanc, its database or its storage area in | |
| 212 folders whose names contain **spaces or special characters**. | |
|
902
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
213 |
|
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
214 * If you run Orthanc as a Windows service, with the Python plugin |
|
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
215 enabled, you might have to change your ``PATH`` environment variable |
|
903
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
216 for Orthanc to **find the Python DLL**. The easiest approach to this |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
217 end consists in configuring the Windows service to **run as user** |
|
902
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
218 (instead of the default ``SYSTEM`` account), `as explained in this |
|
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
219 thread |
|
7f30e05a3319
note about Windows service
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
755
diff
changeset
|
220 <https://groups.google.com/g/orthanc-users/c/axrJfgA-Enk/m/Zeg3iUPOAwAJ>`__ |
|
903
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
221 on the Orthanc Users forum (cf. `additional reference |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
222 <https://docs.microfocus.com/SM/9.61/Hybrid/Content/serversetup/tasks/configure_the_service_manager_service_to_run_as_a_windows_user.htm>`__ |
|
25bbeb754420
note about shared network drives
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
902
diff
changeset
|
223 elsewhere on Internet). |