# Issues

Troubleshoot problems, run diagnostics, and report bugs.

Something not working right? Most issues can be diagnosed in a minute or two with ARI's built-in tools. Here's the order we recommend trying them in.

## 1. Run `./ari doctor`

Your first stop. The doctor command runs a series of health checks on your local install — it verifies your environment, dependencies, database connection, environment variables, and configuration files, then tells you exactly what's wrong (and often how to fix it).

From your ARI directory, run:

```
./ari doctor
```

On Windows, use `.\ari.cmd doctor` instead.

The output is colour-coded — green means good, yellow means a warning, red means something needs your attention. If doctor flags an issue, follow the suggestion it prints. This catches the majority of setup and configuration problems.

## 2. Check the `/health` page

If doctor looks clean but something still feels off, open the **Health** page in your running ARI app:

```
http://localhost:3000/health
```

This is an in-app diagnostic dashboard that tests the running application end-to-end — authentication, database queries, the backup system, storage providers, module loading, API routes, and more. Each test reports pass/fail with details, so you can pinpoint which subsystem is misbehaving.

This is especially useful for issues that only show up at runtime (a specific feature failing, a module not loading, slow queries, etc.) — things doctor can't see from outside the app.

## 3. Open a GitHub Issue

Still stuck? Let us know. Issues are tracked publicly on GitHub so anyone can search, comment, and follow along.

Open a new issue on the [ARI GitHub repo](https://github.com/ARIsoftware/ARI/issues).

Before opening a new one, please:

- Search existing issues to see if it's already been reported.
- Check the latest version — your issue may already be fixed. See [Updating ARI](https://ari.software/docs/updating).
- Include the output from `./ari doctor` and anything red on the `/health` page.

### What to include in a great bug report

- **Summary** — one-line description of the problem.
- **Steps to reproduce** — exactly what you did, in order.
- **Expected behavior** — what you thought should happen.
- **Actual behavior** — what actually happened.
- **Environment** — OS, browser, ARI version, Node version.
- **Diagnostics** — `./ari doctor` output and any failed checks from `/health`.
- **Logs or screenshots** — anything that helps us see what you saw.

## Feature Requests

Feature ideas are welcome. Open an issue with the `enhancement` label and describe the use case — what you're trying to accomplish, not just the feature you want. The more context, the better.

## Your Personal Workspace. Your Rules.

Source Code Available. Self-Hosted. Full Data Control. Fully Extendable. AI Native. Dozens of Built-In Modules And Build Your Own In Minutes. No Coding Required.

[Get Started](https://ari.software/docs/installation)

---

Source: https://ari.software/docs/issues

Markdown rendering of this page, served for `Accept: text/markdown`. Full site index for agents: https://ari.software/llms.txt