> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealmanac.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose installation, authentication, wiki scope, uploads, and jobs.

Start with:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac doctor
almanac whoami
```

## `almanac` is not found

Open a new shell after installation. If needed, reinstall with `uv tool install
the-almanac`, then run `almanac --version`. See [Install the CLI](/getting-started/install).

## The CLI asks you to sign in

Run `almanac login`. For automation, confirm `ALMANAC_TOKEN` contains the actual
`waka_...` secret rather than an API key ID or obfuscated value. Secrets are shown
only once.

## No wiki is selected

Run `almanac whoami`, then either link the project or pass an explicit handle:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac link acme/company-handbook
almanac search "onboarding" --wiki acme/company-handbook
```

Review the [wiki context order](/reference/configuration) if the wrong wiki wins.

## Upload created no job

If the output says `already in library`, every file was a duplicate and no new
job exists. Do not wait on `last`; it still refers to an older job. See [Upload
sources](/guides/upload-sources).

## A job failed or stopped progressing

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac jobs show job_123
almanac jobs events job_123
```

Keep the job ID and final `request_id` or error when reporting the problem. See
[Follow a job](/guides/follow-job) for the available views.

## Search returns no results

Queries need at least two letters or numbers. Confirm the job succeeded, verify
the selected wiki, then browse `almanac pages list` and `almanac sources tree` to
separate a page-generation problem from a missing-source problem.

## MCP will not connect

The intended public MCP hostname is currently called out as unverified on the
[MCP setup page](/mcp/remote). Use the CLI, SDK, or REST API until that warning is
removed; do not substitute an internal service origin.