Troubleshooting

This page targets the stable v0.11.0 release. Start with the checks below to locate the failing segment, then jump to the matching symptom.

Collect facts first

1. Confirm service and state

   curl -fsS http://127.0.0.1:23333/ready
   docker exec depsilo /app/depsilo doctor --json

   /ready checks SQLite and object storage; /health is only a process-liveness signal. They are not interchangeable.

2. See where requests actually went

   Admin → Access logs (/admin/logs) records the ecosystem, package, status, and hit result. The Portal’s Monitor tab shows upstream health, probe latency, and hit rate.

3. Generate a shareable diagnostic report

   If you followed the Docker quick start, write the report inside the container and copy it to your machine:

   docker exec depsilo /app/depsilo diagnose \
     --out /root/.depsilo/depsilo-diagnostic.json
   docker cp depsilo:/root/.depsilo/depsilo-diagnostic.json \
     ./depsilo-diagnostic.json

   If you installed the binary directly, run depsilo diagnose --out depsilo-diagnostic.json on that machine. The report is created with owner-only permissions and omits configuration content, credentials, request samples, package names, and client addresses. Choose a new filename on later runs; the command will not overwrite a report. Review the contents before sharing.

Requests bypass Depsilo

• The localhost trap: inside containers, CI runners, and remote hosts, localhost points at the machine itself, not the host running Depsilo. Use the hostname or IP the client can actually reach.
• Configuration is not being read: confirm the client really uses the new address with npm config get registry, go env GOPROXY, mvn help:effective-settings, or bundle config get mirror.https://rubygems.org. Project-scoped files can override the user-level file you edited.
• The client was not restarted: Docker needs a daemon restart, and some IDEs and build daemons cache the previous configuration.
• A fallback path is still active: extra-index-url, |direct, and Composer’s original dist URL can all bypass Depsilo. See the enforcement boundaries in Connect package managers.

451 responses

Response code	Meaning	What to do
QUARANTINED	The version is younger than the minimum release age	Wait for the threshold, or have an operator approve that (ecosystem, package, version)
MALICIOUS_BLOCKED	The version matches the known-malicious dataset	Do not bypass; verify the package and version, and handle false positives with a recorded temporary override
SNAPSHOT_BLOCKED	Snapshot mode refused a version outside the snapshot	Use a version inside the snapshot, or adjust the snapshot

Approvals and overrides are audited. A malicious-package override lasts at most 24 hours and cannot be extended in place; continued use needs a new recorded decision. See Supply-chain security for the full policy model.

Authentication and the admin surface

• The bootstrap token is for first-run setup only. It must not be reused as a package-manager or MCP credential; MCP uses a regular read-only API token created in Admin.
• There is no default administrator account; the first admin is created during setup. If the password is lost, follow the recovery steps in the deployment guide instead of guessing defaults.
• With an explicit configuration file, auth.jwt_secret = "change-me-in-production" fails startup when binding a non-loopback address. Inject at least 32 random bytes from a secret manager.
• API tokens are stored hash-only and shown in plain text once at creation; if lost, create a new token.

Low hit rate or repeated MISS

• The first request is normally a MISS; only a repeated request is meaningful for verifying caching.
• Metadata and artifacts have separate TTLs: built-in defaults are cache.ttl_index = 5m and cache.ttl_blob = 72h. The sample file is an explicit override, not a default listing.
• The cache has a size limit (default cache.max_size_gb = 20); LRU eviction forces the next request back upstream.
• Responses that carry upstream credentials never enter the shared cache and always reach upstream by design.
• Policy runs before the cache lookup, so a version that exists in the cache can still return 451.

Upstream problems

• /ready deliberately does not check upstreams: Depsilo can keep serving cached artifacts while an upstream is down.
• Upstream selection uses the highest-priority healthy source. After a health check or a request result marks the current source unhealthy, subsequent requests use the backup; the failing request itself is not retried elsewhere.
• Check mirror health and probe latency on the Admin Monitor page; for persistent failures, inspect the upstream URL, network egress, and credentials.
• Deleting the last upstream of an ecosystem returns 409 LAST_UPSTREAM; add a replacement before removing the current one.

Disk, state, and backups

• Configuration and SQLite are always local state; S3 stores object cache only and does not turn the instance into a multi-node or HA deployment.
• The depsilo backup archive contains config.toml and a consistent SQLite snapshot. It does not contain local or S3 cache objects.
• Host-directory mounts must be owned by the image’s fixed 10001:10001 identity and mounted at /root/.depsilo. Switching between a named volume and a host directory means switching to a different set of state.
• Stop the service that owns the target database before restoring, and rehearse the restore in isolation before overwriting production state.

Upgrade and version problems

• Pin a X.Y.Z tag or digest in production instead of latest, and read the target release notes before upgrading.
• When upgrading the binary in daemon mode across versions, first verify that the recorded process has ended; v0.9.1 no longer accepts the v0.9.0 PID-only record, and the old file may need manual cleanup as described in the release notes.
• After an upgrade, re-run /ready, doctor, and one real client fetch. “The container started” is not a success criterion.

Still stuck

Prepare the depsilo diagnose report, doctor --json output, the relevant Access log timestamps, and the client configuration (with credentials removed) before asking for help. Never paste the bootstrap token, API tokens, JWT secret, or a complete configuration file into a public channel.