Documentation /

Troubleshooting

FAQ

General

Does the plugin make external API calls?

No, except for license validation. All DICOM processing and image viewing happens in the browser. The only external call is to the license server to validate your license key (cached for 24 hours). No patient data or file contents are sent externally.

Can I use DICOM Viewer on multiple sites with one license?

No. Each license key is bound to a single WordPress domain. You need a separate license for each site. If you move to a new domain, deactivate the license on the old domain first, then activate it on the new one.

What image formats are supported?

Only DICOM (.dcm) files and ZIP archives of DICOM files. The plugin does not support JPEG, PNG, or other medical image formats. If your images are in another format, use a DICOM converter or your imaging software to export them as .dcm first.

Can I anonymize DICOM files permanently?

Not with this plugin. The Anonymization setting redacts tags in the info overlay only — the actual file is never modified. To permanently remove PHI from files, use external DICOM anonymization tools before uploading to WordPress.

File Uploads

My .dcm file won’t upload. What should I do?

Check the following:

  1. File format — confirm it’s a valid DICOM file (extension .dcm)
  2. File size — check your server’s upload_max_filesize limit in Media > Add New
  3. Server firewall — some hosting providers block .dcm uploads. Contact your host to whitelist the file type.
  4. PHP permissions — ensure WordPress has write permissions to wp-content/uploads/

Try uploading a small test file first. If it works, the issue was file size or content.

Can I upload ZIP files with mixed content?

Only DICOM files inside the ZIP are processed. Non-DICOM files are ignored. If the ZIP contains no valid DICOM files, the upload succeeds but you’ll see an error when you try to display it.

Viewer Display

The viewer shows a blank area. What’s wrong?

Check:

  1. License is active — go to DICOM Viewer > License and verify the status is Active
  2. File uploaded successfully — go to Media > Library and confirm the file appears
  3. Correct file selected — in the Gutenberg block or shortcode, verify the right file is selected

If the file is there and the license is active, try refreshing the page. If it still doesn’t work, check your browser’s console for JavaScript errors (F12 in most browsers).

The viewer loads but shows no image.

This usually means the file isn’t a valid DICOM file, or it’s corrupted. Try:

  1. Re-uploading the file
  2. Using a different DICOM file to test
  3. Checking the file with a DICOM validator tool to confirm it’s valid

The image is too small or too large on the page.

Adjust the viewer height:

  • Globally — DICOM Viewer > General set Default Height
  • Per-viewer — in the Gutenberg block, set Height in the sidebar, or use height="600px" in the shortcode

The width is always 100% (full container width) by default.

Series & Slices

I uploaded a ZIP with multiple series, but only one appears.

Check the Series Settings:

  • If Series Display Mode is set to none, the series selector is hidden. You’ll only see the first series.
  • Change it to auto, pills, or dropdown to display the selector.

The series selector isn’t showing. How do I switch series?

Your settings may have Series Display Mode set to none. Go to DICOM Viewer > Series, and change Series Display Mode to auto, pills, or dropdown.

Cine playback isn’t working.

Cine playback only works with multi-slice series (files with more than one slice). If your file has only 1 slice, cine won’t run. Check that you’re using the right file.

Window/Level & Image Adjustment

I changed the window/level and can’t see the image anymore.

The image is still there — you may have just adjusted the contrast so the visible range no longer includes your anatomy. Click Reset to restore default window/level.

Can I save custom window/level presets?

Not in the current version. Users can manually adjust brightness/contrast using the W/L button in the toolbar, but settings aren’t saved between sessions.

Access & Downloads

Users are getting "403 Forbidden" when trying to download.

This happens when protected file serving is enabled and the file’s access level is too restrictive. Go to Access Control and check the file’s access level. If it’s set to admin, only administrators can access it.

The download button isn’t showing, but I want users to download.

Go to DICOM Viewer > General and enable Allow Download. This shows the download link for all viewers (unless overridden per-viewer).

I deleted a file from the media library, but the shortcode still references it.

The viewer will show an error because the file no longer exists. Update all shortcodes and blocks to remove the deleted file reference.

Grid Layout

Grid layout is making the page very slow.

Rendering 4 panes simultaneously requires significant CPU, especially on large images or slower devices. Try:

  1. Reducing the number of grid columns (Grid Columns setting)
  2. Switching to single-pane layout for users on mobile
  3. Using smaller images or lower resolution datasets

License

My license shows as "Expired". Can I renew it?

Yes. Go to DICOM Viewer > License and click the Renew link, which takes you to webdevelop.hu to purchase a renewal.

The license validation shows "Grace Period". Should I be concerned?

No. This means the license server is temporarily unreachable, but the plugin continues to work for up to 7 days. Once the server is back online, validation will succeed. If it remains unreachable for 7+ days, contact support.

I lost my license key. How do I find it?

Log in to your account at webdevelop.hu to retrieve your key. If you can’t find it, contact support at the same domain.

Support

If your question isn’t answered here, contact support at webdevelop.hu.

Common Issues

"License is inactive" message

Symptom: Viewer shows "License is inactive" or the block/shortcode doesn’t work.

Solution:

  1. Go to DICOM Viewer > License
  2. Check the status badge
  3. If it says Inactive, enter your license key in the field and click Activate License
  4. If it says Expired, you need to renew your license at webdevelop.hu
  5. If it says Grace Period, the license server is temporarily unavailable — the viewer will work for up to 7 days

File upload fails silently

Symptom: You try to upload a .dcm file but nothing happens.

Solution:

  1. Check file size — WordPress shows the maximum upload size in Media > Add New. If your file is larger, increase upload_max_filesize in your hosting control panel.
  2. Check server firewall — some hosts block .dcm uploads by default. Contact your hosting provider to whitelist DICOM files.
  3. Check PHP memory — very large files may exceed PHP memory limits. Increase memory_limit if available.
  4. Try a smaller file — test with a small DICOM file to isolate the issue.

"404 Not Found" when clicking download

Symptom: Download link appears, but clicking it shows a 404 error.

Cause: Protected file serving is enabled, but WordPress rewrite rules aren’t configured correctly.

Solution:

  1. Go to Settings > Permalinks
  2. Click Save Changes (even though you haven’t changed anything)
  3. This flushes the rewrite rules so /dv-file/ routes work properly

"403 Forbidden" when accessing file

Symptom: File download shows a 403 Forbidden error.

Cause: Protected file serving is on, and your user doesn’t have access to the file.

Solution:

  1. Check the file’s access level (stored in _dv_access meta)
  2. Verify your user role has access:
    • public — anyone
    • logged_in — logged-in users
    • admin — administrators only
  3. If needed, change the access level to logged_in or public

See Access Control for details.

Viewer renders but image is blank

Symptom: Viewer loads (you see the toolbar), but no image appears.

Cause: Usually the file isn’t a valid DICOM file, or it’s corrupted.

Solution:

  1. Verify the file is a valid DICOM file using a DICOM tool or your imaging software
  2. Try uploading and viewing a different DICOM file to test
  3. If only one file fails, it may be corrupted — try re-exporting it from your imaging software

Shortcode shows as plain text

Symptom: The page displays instead of showing a viewer.

Cause: License is inactive, so the shortcode handler is disabled.

Solution:

  1. Activate your license key (see "License is inactive" message above)
  2. Clear any page caches on your site
  3. Refresh the page in your browser

Gutenberg block isn’t appearing

Symptom: The DICOM Viewer block doesn’t show in the block inserter.

Cause: License is inactive.

Solution:

  1. Activate your license key (see "License is inactive" message above)
  2. Refresh the page or clear editor caches
  3. The block should appear when you search for "DICOM"

Grid layout is performing poorly

Symptom: Viewer is slow, laggy, or freezes when using grid layout with multiple panes.

Cause: Your device doesn’t have enough CPU/GPU to render multiple panes.

Solution:

  1. Reduce grid columns (DICOM Viewer > Series Settings)
  2. Switch to 2-pane grid instead of 4-pane
  3. Use single-pane layout (layout="single") for mobile users
  4. Test on a faster device to confirm the file works

"Protected serving is enabled but file serves directly"

Symptom: Even with protected serving on, files download from direct URLs instead of /dv-file/

Cause: The file doesn’t have the _dv_secure_file meta set.

Solution:

  1. Files uploaded after enabling protected serving are marked automatically
  2. For files uploaded before enabling it, manually set the meta:
update_post_meta( $attachment_id, '_dv_secure_file', '1' );

"Mixed content" security warning

Symptom: Browser shows a warning that the page contains "insecure" content.

Cause: Your site uses HTTPS but the DICOM file is served over HTTP.

Solution:

  1. Ensure your WordPress site runs on HTTPS (not HTTP)
  2. If using external file URLs, make sure they’re also HTTPS
  3. Update your Settings > General URL to use https://

PHP errors in debug log

Symptom: wp-content/debug.log shows errors from the DICOM Viewer.

Solution:

  1. Check if the license is active (license-related errors)
  2. Check file permissions on wp-content/uploads/
  3. Check PHP memory limit if handling large files
  4. Contact support at webdevelop.hu with the error message

License validation fails repeatedly

Symptom: License shows "Inactive" even though you entered a valid key.

Cause: The license server couldn’t validate your key.

Solution:

  1. Check your key — make sure you copied it correctly (they’re case-sensitive)
  2. Check connectivity — your server must be able to reach https://webdevelop.hu. Ask your hosting provider if outbound HTTPS is blocked.
  3. Check domain — the key must be activated for the domain you’re using it on
  4. Grace period — if validation fails, the plugin enters a 7-day grace period and continues to work

If the issue persists, contact support.

File deleted but shortcode still shows

Symptom: Shortcode references a file that was deleted from the media library.

Cause: The viewer tries to display the file, but it no longer exists.

Solution:

  1. Go back to the page/post with the shortcode
  2. Update the shortcode to use a different file ID, or
  3. Delete the shortcode if you no longer need it

Use Media > Library to find the correct file ID for the file you want to use.

Need More Help?

For issues not listed here, contact support at webdevelop.hu. Include:

  • Your WordPress version and PHP version
  • Steps to reproduce the problem
  • Any error messages from the browser console (F12) or WordPress debug log
  • Description of your server setup (shared hosting, VPS, managed WordPress, etc.)

© 2026 webdevelop.hu — Custom WordPress / WooCommerce Development & Migration Specialist — Contact