---
title: Archbee CLI Troubleshooting
slug: docs/archbee-cli-troubleshooting
docTags: 
createdAt: 2026-08-25T09:37:14.629Z
---

## Troubleshooting the Archbee CLI

This guide covers the most common problems users encounter when working with the Archbee CLI.

Use these troubleshooting steps before opening a support ticket. Most issues can be resolved by validating your setup, checking authentication, or reviewing the CLI command options.

:::::ExpandableHeading
### CLI Does Not Start

**Problem**

Running `archbee` fails or does nothing.

**Recommended Steps**

::::WorkflowBlock
:::WorkflowBlockItem
Run `archbee version` to verify the CLI is installed.
:::

:::WorkflowBlockItem
Reinstall the CLI globally using npm if the command is missing.
:::

:::WorkflowBlockItem
Restart your terminal session and try the command again.
:::
::::

**Install Command**

```bash
npm install -g @archbee/cli
```
:::::

:::::ExpandableHeading
### Hot Reload Is Not Working

**Problem**

Changes are not updating in the local preview.

**Recommended Steps**

::::WorkflowBlock
:::WorkflowBlockItem
Restart the local development server using `archbee dev`.
:::

:::WorkflowBlockItem
Verify your project contains a supported config file.
:::

:::WorkflowBlockItem
Check that your documentation folder is not ignored or excluded.
:::
::::
:::::

:::ExpandableHeading
### Broken Links Are Not Being Detected

Run:

```bash
archbee broken-links
```

Make sure your internal links use valid relative paths.
:::

:::ExpandableHeading
### OpenAPI Sync Problems

**Problem**

`sync-openapi` fails during import.

**Common Causes**

- Invalid OpenAPI schema
- Unsupported references
- Incorrect file path
- Missing authentication

**Recommended First Step**

Validate the OpenAPI file before syncing.
:::

:::ExpandableHeading
### Authentication Errors

**401 Unauthorized**

Usually caused by:

- Invalid API key
- Expired token
- Wrong space ID

**403 Forbidden**

Usually caused by missing permissions or a read-only team API key.
:::

:::ExpandableHeading
### Publishing Problems

**Problem**

`publish-space` fails.

**Solution**

Verify:

- You have write permissions
- The space ID is correct
- The API key belongs to the correct organization
:::

:::::ExpandableHeading
### Recommended Debugging Workflow

::::WorkflowBlock
:::WorkflowBlockItem
Run `archbee validate` to verify project structure.
:::

:::WorkflowBlockItem
Run `archbee broken-links` to scan internal links.
:::

:::WorkflowBlockItem
Use `archbee <command> --help` to review command usage and arguments.
:::
::::
:::::

## Additional Resources

- Main docs: [https://archbee.com/docs](https://archbee.com/docs)
- npm package: [https://www.npmjs.com/package/@archbee/cli](https://www.npmjs.com/package/@archbee/cli)
- CLI help: `archbee --help`