Skip to content

17 Troubleshooting Handbook

Use symptom-first troubleshooting to separate transport issues, auth failures, content problems, and index drift quickly. This approach avoids blind retries and reduces mean time to recovery.

17.1 Prerequisites

  • Access to container logs and mounted config/workspace paths.
  • A reproducible failing command.
  • Permission to run diagnostic CLI/API requests.

17.2 Quick Start

  1. Capture the exact command, error output, and timestamp.
  2. Verify endpoint, protocol (http or https), and auth mode.
  3. Re-run a minimal diagnostic command.
  4. Correlate with logs in the same time window.
  5. Apply one fix at a time and re-test the same command.

Minimal diagnostics:

curl -sS "http://localhost:19191/athene/debian/list-packages"
athene ls
athene debian list-packages main

17.3 Key Parameters Explained

  • Endpoint and scheme: http://localhost:19191 vs https://localhost:19443 mismatch causes many false alarms.
  • Auth mode options (--pat, --username, --password-stdin): incorrect combinations fail early.
  • ATHENE_MAX_FILE_SIZE and ATHENE_MAX_REQUEST_SIZE: import failures for large artifacts often map here.
  • ATHENE_ALWAYS_ALLOW_CIDRS: can hide auth behavior differences between local and remote clients.

Tip

If import reports success but package is missing, verify repository selector and index output before re-uploading. Duplicate uploads usually add noise without fixing root cause.

17.4 Common Failure Playbooks

A) Install/startup failures

  • Check container is running and ports are mapped.
  • Confirm mounted config/workspace paths exist and are writable.
  • Inspect startup logs for keystore or path errors.

B) Authentication failures

  • Confirm server is actually in authenticated mode.
  • Verify you are not mixing PAT and username/password in one command.
  • Re-test with a fresh PAT.

C) Import/indexing failures

  • Validate local file path and artifact integrity.
  • Run import once, then verify with list-packages.
  • Use athene reindex only when index drift is strongly indicated.

D) Sync/export failures

  • Confirm destination URI is writable.
  • Ensure available disk space.
  • Retry with a local file:/// destination before testing remote targets.

E) ACL and user issues

  • Check effective global ACL and per-repo overrides.
  • Verify user role and token freshness.
  • Test with a known admin account to isolate policy from transport/auth issues.

Next chapter: 18 Glossary.