# Troubleshooting

Common issues and how to resolve them.

***

## "Not logged in. Run 'hu login' to authenticate."

Most CLI commands require authentication. Run `hu login` to open a browser window and sign in with your Health Universe account.

If you've already logged in and still see this error, your credentials file may be missing or corrupted. Run `hu login` again to generate a fresh token.

***

## "Session expired. Run 'hu login' to re-authenticate."

Authentication tokens are valid for 24 hours. After that, you need to log in again:

```bash
hu login
```

You can check your current authentication status at any time with:

```bash
hu config show    # Shows token status: valid, expired, or not set
hu whoami         # Shows your user info if authenticated
```

***

## Login times out or browser doesn't open

The `hu login` command opens a browser window and waits up to **2 minutes** for you to complete sign-in. If it times out:

1. Run `hu login` again
2. If the browser doesn't open automatically, the CLI prints a URL you can copy and paste into your browser manually

If you're on a headless server or remote machine without a browser, you'll need to log in from a machine with a browser and copy the credentials file (`~/.hu/credentials`) to the remote machine.

***

## "Failed to fetch..." or generic API errors

These errors usually mean the CLI couldn't reach the Health Universe API. Check the following:

1. **Are you connected to the internet?**
2. **Is the API URL correct?** Run `hu config show` to verify. The default production URL is `https://apps.healthuniverse.com`.
3. **Are you logged in?** Run `hu whoami` to check.
4. **Is the server up?** Try opening `https://www.healthuniverse.com` in your browser.

If you previously changed the API URL for local development and forgot to switch back:

```bash
hu config set apiUrl https://apps.healthuniverse.com
hu config set authUrl https://www.healthuniverse.com
```

***

## Workspace-related errors

Some commands require an active workspace to be selected. If you see unexpected results or empty lists:

1. Check which workspace you're in: `hu whoami`
2. List available workspaces: `hu orgs list`
3. Switch to the correct workspace: `hu orgs switch my-org`

> `hu projects list` requires an active workspace. `hu apps list` defaults to your personal workspace if none is selected.

***

## Deploy with `--wait` exits before deployment finishes

The `--wait` flag polls for up to **10 minutes**. If your deployment takes longer (common for large applications or first-time builds), the CLI exits but the deployment continues on the server.

To check progress after the CLI exits:

```bash
hu apps status <app-id>
hu apps logs <app-id>
hu apps logs <app-id> --build    # If still building
```

***

## Resetting the CLI

To start completely fresh, use the built-in reset command:

```bash
hu config reset           # Clears config + token
hu config reset --keep-token   # Clears URLs/workspace but preserves the token
hu login                       # Re-authenticate if needed
```

This clears your stored token, configuration, and workspace selection.

You can also nuke the entire local data directory directly:

```bash
rm -rf ~/.hu
hu login
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.healthuniverse.com/overview/command-line-interface/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.