Skip to main content

Troubleshooting

Use this page for first-line diagnosis and the standard support bundle.

If you already know you need command-family context for logs, metrics, cache, journal, or trace commands, read Operations for users.

If this page is not enough, continue with Validation and runbooks.

Aether CLI cannot reach the service​

Check these first:

  • Is AFS_AETHER_SERVER_ENDPOINT set correctly?
  • If you use config, is [bridge].server_endpoint correct?
  • Can your machine reach the target hostname and port?
  • Does the shell launching aether have the credentials your deployment expects?

Useful command:

aether doctor

aether doctor checks local prerequisites such as FUSE availability, kernel support, and mount-directory sanity. It does not prove that your endpoint, credentials, or session permissions are correct.

Mount command fails immediately​

Possible causes include:

  • Incorrect endpoint.
  • Missing or invalid auth context.
  • Invalid session ID.
  • Unsupported or incorrect mount flags.
  • Local filesystem permission issues around the mount directory.

Check:

aether mount --help
aether doctor

Then rerun the mount with explicit endpoint/auth settings and readable logs:

export AFS_AETHER_LOG='debug'
export AFS_AETHER_LOG_FORMAT='text'
aether mount --session-id '<session-id>' --mount-dir ./workdir

aether status is not helpful​

aether status is for inspecting the running local runtime. It is not the same thing as a generic network probe.

If nothing is running yet, start with endpoint, auth, and doctor instead.

Local behavior seems stale​

If mounted content or directory listings do not reflect expected changes quickly enough, review TTL settings:

  • AFS_AETHER_LOOKUP_TTL_SECS
  • AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS
  • AFS_AETHER_DIR_CACHE_TTL_SECS

Shorter TTLs usually improve freshness at the cost of more remote lookups.

Logs are hard to consume​

Adjust:

  • AFS_AETHER_LOG
  • AFS_AETHER_LOG_FORMAT

Use text for local debugging and json for machine ingestion.

Metrics are unavailable​

Check whether metrics are enabled through:

  • AFS_AETHER_CLIENT_METRICS_ADDR
  • metrics_addr

Then use:

aether metrics show

aether metrics show prints the configured metrics endpoint. If you need live samples, scrape the printed /metrics URL directly.

If multiple environments or workflows reuse the same cache root, issues can become harder to reason about.

Set these explicitly:

  • AFS_AETHER_CACHE_DIR
  • AFS_AETHER_CACHE_SHARED_ROOT

Use separate cache roots for:

  • Different environments.
  • CI versus interactive work.
  • Shared versus personal workflows.

What to capture before asking for help​

Collect:

  • The aether version.
  • The endpoint setting in effect.
  • Relevant env vars or config overrides, with secrets redacted.
  • The exact command you ran.
  • The error text.
  • Any useful aether doctor, aether status --session-id ..., aether logs tail, or aether metrics show output.

A good capture set looks like:

aether --version
aether doctor
aether status --session-id "$SESSION_ID" || true
aether logs tail --lines 200
aether metrics show

If the issue goes beyond the basic path above, continue with Validation and runbooks.