Skip to content

Troubleshooting

Use these checks to find why Tuvima Library cannot start, find files, or complete an import. Most checks take a few minutes. Keep any error text and the time it occurred.

A Docker container does not become healthy

  1. Confirm all seven persistent mounts exist and have the intended permissions.

  2. Validate the edited configuration.

  3. Inspect startup and health:

    Terminal window
    docker compose config --quiet
    docker compose ps
    docker compose logs --tail=100 tuvima
    docker inspect --format '{{.State.Health.Status}}' tuvima-library

  4. Repair the host folder ACL or configured UID/GID if logs report denied access.

  5. Confirm Dashboard port 5016 is not already used.

Do not expose Engine port 61495 or enable privileged mode to work around startup failures. See Docker installation.

The Engine does not start from source

Run from the repository root and check dotnet --version. global.json requests stable SDK 10.0.100 with latestFeature roll-forward.

If restore cannot find Tuvima.Wikidata*, inspect nuget.config. This checkout uses nuget.org, while some local setups map those packages to the sibling tuvima-wikidata/artifacts feed. Check that feed before changing package references.

Review config/core.json and config/libraries.json for machine-specific paths. Stop an older Engine or Dashboard instance before starting another.

The Dashboard cannot reach the Engine

For source runs, start the Engine first:

Terminal window
dotnet run --project src/MediaEngine.Api

Wait for http://localhost:61495, then start the Dashboard in another root terminal:

Terminal window
dotnet run --project src/MediaEngine.Web

Set TUVIMA_ENGINE_URL before launching the Dashboard when the Engine address differs.

Both apps must resolve the same TUVIMA_CONFIG_DIR and data-protection keys. The Engine writes a protected Dashboard credential there. Check the resolved credential path in Dashboard logs if requests report temporary unavailability.

The Dashboard retries credentials on later requests and detects replacement. Do not copy a credential from another Engine data store or disable authentication to recover.

Sign-in or administrator settings are unavailable

Check the active account, profile grant, and Users and Sign-in → Sign-in Methods settings.

Account access from outside needs the sign-in methods you allow under Users and Sign-in → Sign-in Methods and a secure path (Tailscale or an HTTPS reverse proxy; the Dashboard itself serves plain http). Administrator settings require account eligibility and an administrator-enabled active grant; optional grant PIN protection may also need unlocking.

Use account recovery if your password and authenticators are unavailable. A request from localhost alone never grants administration.

Home is empty

Home shows real library results. Check:

  1. Settings → Libraries for sources, media types, and path access.
  2. Settings → Providers for enabled providers and connection results.
  3. Operations at /settings/ingestion for active or waiting work.
  4. Settings → Review Queue for uncertain items.

A catalogue item needs a real title, resolved type, and settled artwork state before browsing. View assets use their own local index and permissions.

Files do not import

  1. Confirm the Engine can read the server-side source path.
  2. In Docker, use a container path and check its mount.
  3. Confirm the extension and library media type match supported media types.
  4. Wait for copying to finish and release locks held by other programs.
  5. Use Check folders for changes (in the Ingestion page ”⋯” menu) in Operations after changing source folders.

For View, confirm the owning profile, source attachment, and upload/import policy. Routine catalogue scans do not replace View’s personal-source workflow.

When a folder job wants to change only the letter case of a file’s name (or of a folder in its path), Tuvima first checks that the old and new names are the same file. If it cannot prove that, the rename is skipped with a warning in the Engine log and in the folder job’s log, and is never forced; the file keeps its current letter case. This happens when the file is held open by another program, and on shares that do not support file locks, such as a CIFS mount with noserverino,nobrl or some NFS setups. Close the program using the file, rename it by hand, or mount the share with file locking enabled, then run the job again.

An import waits or needs review

Operations reports durable queued jobs, retries, and provider waits. A settled file count can reach its target while required identity or organization work remains.

Restarted imports resume recoverable jobs. Use Settings → Review Queue for unclear matches, conflicting metadata, unreadable files, or ambiguous media types. Read the specific reason before changing anything.

Optional lyrics, subtitles, or commercial detection returning no result usually do not require identity review.

Provider lookups fail

  1. Confirm the provider is enabled.
  2. Use its saved Test connection action.
  3. Check required credentials, server network access, and provider rate limits.
  4. Inspect the provider’s safe status message.

Long-lived keys belong in config/secrets/. A blank key in the public provider definition may have an effective secret overlay. Do not include keys in logs or support reports.

Tags or the profile name haven’t reached a file yet

Library saves changes at once, but writes them into files on a schedule, every 60 minutes by default. A change is usually in the file after the next run.

  1. Wait for the next run. The editor’s Files card and the write panel in Settings > Libraries > Advanced show Next run.
  2. To write now, press Write now (administrators, on a desktop).
  3. If the panel says files couldn’t be written, open the list and read the reason for each file. A file that is busy, on an unplugged drive or read-only is tried again on the next run. A file that can’t hold tags is kept in Library only and is not retried.
  4. If the panel says Photos, videos and PDFs in View are waiting for ExifTool, check Settings > Tools and requirements. Library fetches ExifTool by itself when it is missing. Use Download again there if it did not finish.

Local AI is unavailable

Open Settings → Tools and requirements. Check whether a model is missing, downloading, ready or failed, and use Download again if a download did not finish. Loading and unloading a model are on the same page; the runtime limits are on Settings → Local AI → Runtime.

Confirm model storage, native runtime availability, and capability gates. Switching an AI plugin on does not make missing dependencies ready. Local AI is optional for initial catalogue setup.

Sending logs with a bug report

A server administrator opens Settings > System > Logs > Export, chooses the time range, the level (errors only, warnings and errors, or everything), the areas, and optionally one run or item id, then presses Download. The page first says how many lines and how large the file will be. The result is one text file, tuvima-logs-{start}-{end}.txt, with a short header that lists what was chosen.

The file hides private details before it is written:

  • Keys and tokens: bearer values, values that follow api_key=, token=, secret= or password=, sign-in tokens and long unbroken strings of letters and digits. Run and item ids are kept, because a report needs them.
  • Sign-in details: email addresses and the user named in a sign-in message.
  • File and folder names: every path becomes [path]. Turn on Show file names to keep the last part of each file name (for example [path]/Dune.mkv); the folders stay hidden either way.

Check the file before you share it: hiding works on patterns, so a private detail written in an unusual way may remain. Events from the Library’s own activity log are added when the level is Everything and Include events is on.

The documentation site looks stale

The site is built from the tuvima-docs repository by its documentation workflow. Check the latest eligible main run there before assuming edits are published.

Preview from the site/ folder of that repository:

Terminal window
npm ci
npm run build
npm run preview
Technical details: inspect durable operation and capability state

Authorized diagnostics can inspect:

  • GET /operations?queueName=ingestion
  • GET /ingestion/media-groups/{groupId}
  • GET /assets/{id}/capabilities

These are internal Engine actions, subject to authentication and operation/resource permissions. Do not publish the Engine to reach them.

Useful operation states include discovered, settling, waiting_for_lock, queued, hashing, parsing, scoring, registered, queued_identity, and completed. Interrupted work remains visible after restart.

Capability rows distinguish pending, queued, running, no_result, blocked, failed_retryable, failed_terminal, dead_lettered, and stale. Missing output alone does not prove a provider ran or found nothing.

Next steps