Issues

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.

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.
• 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.