Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShaneIsrael/fireshare/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the most frequently encountered problems when running Fireshare. Each section describes the symptoms, explains the root cause, and provides the exact steps or commands needed to resolve the issue. If your problem is not listed here, check the container logs first — they are the best source of detail for unexpected errors. 
docker logs fireshare
Videos are discovered by a background scan that runs every MINUTES_BETWEEN_VIDEO_SCANS minutes (default: 5). If a video is not showing up, work through the following checklist:
  1. Wait for the next scan. The scan runs on an interval; new files will not appear instantly. You can also trigger a manual scan from the admin panel.
  2. Confirm the volume is mounted correctly. The container expects source videos at /videos. Verify the volume mapping in your docker-compose.yml or docker run command: 
    - /path/to/your/clips:/videos
  3. Check supported file extensions. Only .mp4, .mov, and .webm files are scanned. Files with other extensions are silently ignored.
  4. Chunk files are skipped. Files with extensions like .part0000 (in-progress uploads) are intentionally ignored until the upload is complete.
  5. macOS sidecar files are skipped. Files prefixed with ._ are filtered out automatically.
  6. Duplicate detection. If a video with the same content hash already exists in the database, the new file is skipped. Check whether the same clip exists under a different path.
  7. Review container logs for scan errors: 
    docker logs fireshare
If video playback is slow, buffering, or failing entirely, try the following:
  • Reduce source file size or bitrate. High-bitrate files require adequate upload bandwidth on the host server.
  • Use browser-compatible formats. MP4 with H.264 video is the most universally supported format for browser playback. Some codecs (AV1, HEVC) may not play in all browsers without a transcode.
  • Enable transcoding with H.264. Setting ENABLE_TRANSCODING=true can produce more compatible versions, but only if the encoder preference is set to H.264 in Settings → Transcoding. AV1 transcodes may still not play in all browsers.
  • Test in another browser. Chrome supports more formats than Safari or Firefox in some cases. Narrow down whether the issue is browser-specific.
  • Check .webm files. WebM containers must use VP8, VP9, or AV1 video codecs to play natively in browsers. WebM with H.264 video is not supported by any browser.

​
Behind a Reverse Proxy (Nginx, Traefik, etc.)

Proxies often have default limits that are too small for large video uploads.Nginx — add to your proxy configuration:
client_max_body_size 0;
proxy_read_timeout 999999s;
Traefik — increase the responseHeaderTimeout and body size limit via your static configuration and middleware. Refer to the Reverse Proxy page for full examples.Other proxies — apply equivalent upload size and timeout settings.

​
Direct Upload (no proxy)

  • The internal Nginx in the container has no file size restriction by default.
  • Gunicorn workers time out after 120 seconds. Very large uploads over a slow connection may hit this limit. Consider increasing GUNICORN_WORKERS or switching to a faster connection.
The container runs as the user/group identified by PUID/PGID (default: 1000/1000). All three mounted directories must be readable and writable by this user.Symptoms:
  • Videos scanned but symlinks fail to create
  • Database not initialising on first run
  • Transcoded files not appearing in /processed/derived/
  • Errors containing Permission denied in container logs
Preferred fix — set PUID and PGID to match the user that already owns your directories:
PUID=1001
PGID=1001
Run id your-username on the host to find the correct UID/GID values.Alternative — change ownership of the directories to match the container’s default user:
chown -R 1000:1000 /path/to/data /path/to/processed /path/to/videos
On NFS mounts, ensure the NFS export grants the correct UID/GID permissions at the server level regardless of which approach you use.
  1. Default credentials are admin / admin if ADMIN_USERNAME and ADMIN_PASSWORD are not set.
  2. Credentials set via environment variables are applied on every startup. If you changed ADMIN_PASSWORD in your docker-compose.yml and restarted, the admin account password was updated to that value.
  3. DISABLE_ADMINCREATE=true with no existing admin user results in no admin account. Remove this variable, restart to let the admin account be created, then re-enable it if needed.
  4. LDAP users cannot log in with local passwords. If LDAP is enabled and the user was imported via LDAP, they must authenticate through LDAP only.
  5. Verify admin account state by checking the database directly: 
    docker exec fireshare sqlite3 /data/db.sqlite "SELECT username, admin FROM user WHERE admin=1 AND ldap=0;"
If users are logged out every time the container restarts, SECRET_KEY is not set.Without SECRET_KEY, a random key is generated on each startup, which invalidates all existing session cookies.Fix — set a stable, random value in your environment:
SECRET_KEY=some-long-random-string-here
Generate one with:
python3 -c "import secrets; print(secrets.token_hex(32))"
Add the generated value to your docker-compose.yml and restart the container. Existing sessions will be invalidated once on the restart when the new key first takes effect.

​
Transcoded videos not appearing

  1. Confirm ENABLE_TRANSCODING=true is set in your environment.
  2. Check that auto_transcode is enabled in Settings → Transcoding within the UI (this is written to /data/config.json and is separate from the environment variable).
  3. Transcoding runs as part of the background scan. Wait for the next scan cycle or monitor the real-time progress in the file manager.
  4. Source videos with a height equal to or less than the target resolution are skipped (for example, a 720p source will not produce a 1080p transcode).

​
GPU transcoding not working

  1. Confirm your GPU supports NVENC. A GTX 1050 or newer is required for H.264; an RTX 40 series GPU is required for AV1.
  2. On Unraid, add --gpus=all to Extra Parameters and set NVIDIA_DRIVER_CAPABILITIES=all.
  3. On standard Docker, add runtime: nvidia or --gpus all to your Compose or docker run command.
  4. If GPU encoding fails, Fireshare automatically falls back to CPU encoding. Check logs to confirm which encoder is being used.

​
Encoder fallback order (when TRANSCODE_GPU=true)

PriorityEncoderRequirement
1AV1 via GPU (av1_nvenc)RTX 40 series or newer
2H.264 via GPU (h264_nvenc)GTX 1050 or newer
3AV1 via CPU (libsvtav1)Any CPU
4H.264 via CPU (libx264)Universal fallback

​
Manually transcoding a specific video

A video can be manually queued for transcoding via its detail/edit page in the UI, regardless of whether auto_transcode is enabled.

​
Discord

The DISCORD_WEBHOOK_URL must match the format:
https://discord.com/api/webhooks/{id}/{token}
An incorrectly formatted URL will cause a validation error on startup. Check container logs immediately after starting the container:
docker logs fireshare

​
Generic Webhook

Both GENERIC_WEBHOOK_URL and GENERIC_WEBHOOK_PAYLOAD must be set together. If only one is provided, the app will exit with a fatal error on startup. The payload must be valid JSON.Verify that both variables are present:
docker exec fireshare env | grep GENERIC_WEBHOOK
See Notifications for the full payload reference and templating options.
See the LDAP configuration page for full setup instructions.Common causes:
  • LDAP_ENABLE must be true along with all connection variables: LDAP_URL, LDAP_BINDDN, LDAP_PASSWORD, LDAP_BASEDN, and LDAP_USER_FILTER.
  • User filter format: Use {input} as a placeholder for the username entered at login. Example: uid={input}.
  • Admin group not working: Admin group membership is determined via the memberOf attribute in LDAP. Ensure your LDAP server populates memberOf and that LDAP_ADMIN_GROUP matches the full DN of the group.
  • LDAP users appearing as non-admin: If a user was previously created as a local account before LDAP was enabled, they may have incorrect flags. The LDAP login flow sets the ldap=true flag on the user record after the first successful LDAP login.
During a video scan, a lock file is created at /data/fireshare.lock to prevent concurrent scans. If the scan process crashes without cleaning up, the lock file remains and subsequent scans will not run.Fireshare automatically detects and removes stale locks from processes that are no longer running. This detection happens at the start of each scan cycle.If scans appear permanently stuck even after restarting the container, manually remove the lock:
docker exec fireshare rm /data/fireshare.lock
Then trigger a manual scan from the admin panel or wait for the next automatic scan interval.
When a video fails validation (during metadata extraction or transcoding), it is recorded in /data/corrupt_videos.json and skipped in all future scans.Symptoms:
  • A video file exists on disk but never appears in the UI
  • Container logs show: "There may be a corrupt video in your video Directory"
Notes:
  • AV1-encoded source files may be flagged as corrupt due to false positives during initial frame decoding. This is a known limitation.
  • A video marked as corrupt can still be manually queued for transcoding via the UI, which uses a more lenient validation pass.
To clear the corrupt list and re-evaluate all flagged files:
docker exec fireshare truncate -s 0 /data/corrupt_videos.json
Then wait for the next background scan to re-evaluate the files. Any genuinely corrupt file will simply be re-added to the list.
Fireshare uses SQLite with WAL (Write-Ahead Logging) mode for concurrent access. Most database issues are caused by filesystem problems on the volume holding /data.Common causes:
  • /data is on a network filesystem (NFS, SMB/CIFS) that does not support POSIX file locking — SQLite WAL mode requires proper flock support. Move the data directory to a local disk.
  • Insufficient disk space on the volume holding /data.
  • The database file was corrupted by a hard shutdown mid-write.
Check database integrity:
docker exec fireshare sqlite3 /data/db.sqlite "PRAGMA integrity_check;"
If the integrity check returns anything other than ok, restore from a backup or delete db.sqlite to let Fireshare recreate it from scratch. All video metadata will be re-discovered on the next scan, but custom titles, descriptions, and tags will be lost.
Deleting db.sqlite is irreversible. All custom titles, descriptions, tags, game links, and view counts will be permanently lost. Only do this if you have no backup and the database is unrecoverable.

Environment Variables

Full reference for SECRET_KEY, PUID, PGID, DOMAIN, and all other configuration variables.

Transcoding

Detailed guide to enabling CPU and GPU transcoding, encoder selection, and resolution settings.

LDAP

Complete LDAP setup and troubleshooting including memberOf attribute requirements.

Reverse Proxy

Nginx, Traefik, and Caddy configuration for large uploads, streaming, and SSL termination.

Notifications

Discord and generic webhook setup, payload templates, and validation requirements.

File Manager

Bulk operations, orphaned derived file cleanup, and the SSE transcoding status stream.

Build docs developers (and LLMs) love

Get started for freeTalk to us