VTunedocs

Operations

Troubleshooting#

Start with the narrowest observable boundary: container health, application logs, reverse proxy, Discord configuration, then the browser. Avoid deleting data or regenerating credentials until the failure is understood.

Run the read-only operator diagnostics from the pinned image before changing the installation. The report includes the VTune version, Node.js, storage access, SQLite integrity and referenced files, application configuration, FFmpeg, FFprobe, and yt-dlp without printing configured paths or credentials:

docker compose -f compose.release.yaml run --rm --no-deps vtune \
  node dist/scripts/doctor.js

Use --json for monitoring or support automation. In the default mode, exit status 0 means the configured instance passed the pre-start gate, 1 means it is not ready, and 2 means the diagnostic command itself could not run. --image-smoke is narrowly reserved for secret-free release-image CI: it skips application configuration, keeps ready false, visibly reports that instance readiness was not evaluated, and uses imageSmokePassed for its packaging-only result.

Login loops or OAuth errors#

  • Confirm PUBLIC_BASE_URL exactly matches the browser origin.
  • Confirm the Discord redirect URI ends with /auth/discord/callback.
  • Check system time, HTTPS validity, cookie security, and proxy forwarding headers.
  • Verify the member belongs to an allowed guild and is invited to the instance.

Bot is offline or will not join#

  • Check the bot token without printing it.
  • Confirm the guild is in ALLOWED_GUILD_IDS.
  • Verify the bot can view, connect, and speak in the selected channel.
  • Check that the requester is present in that voice channel.

Upload or conversion fails#

  • Compare the file size and duration with configured limits.
  • Confirm free space remains above MIN_FREE_STORAGE_BYTES.
  • Verify FFmpeg and ffprobe are available inside the container.
  • Review the upload job in the dashboard and the related structured log event.

Playback fails#

  • Test a known library track before testing an external URL.
  • Re-check requester access if group membership or sharing changed.
  • Confirm Discord voice connectivity and FFmpeg availability.
  • For external URLs, verify yt-dlp can still obtain metadata within the timeout.

Get more evidence#

Use the authenticated Admin runtime strip to capture the exact VTune version, build revision, readiness state, and approved-server coverage. Add the timestamp, affected guild and channel IDs, sanitized log event names, and exact user-visible error. Never publish tokens, OAuth secrets, session cookies, setup links, media, or personal Discord metadata.