Troubleshooting

The messages below are the ones people meet most often. Each one says what it means and what to do.

"no aarshi.toml in this folder"

You are not inside a project created by aarshi setup. Move into the project folder first (the one that contains aarshi.toml), then run the command again.

"Tailwind is not wired"

aarshi status reports this when the styles would not be compiled. Use one of the two ways Tailwind CSS 4 can be connected:

• in next.config.ts, the Turbopack loader @tailwindcss/turbopack for *.css files;
• or a postcss.config.* file that uses the @tailwindcss/postcss plugin.

You need only one of them.

"use -s <section> <page> for a section, -p <page> for a page"

aarshi add <name> without a flag does not know what to add. Choose the flag: -p for a page, -s for a section, -c for a component. Or run aarshi add alone and answer the menu.

"page `…` does not exist"

You asked for a section in a page that is not in views/. aarshi asks whether to create it: answer y to create the page and add the section to it, or n to stop without changing anything.

Empty values reported as todo

A dictionary has keys with no text yet, typically after aarshi add-lang. This is not an error, and the exit code stays 0. Fill the values in lib/i18n/dictionaries/<code>.ts. Run aarshi status --errors-only to hide them while you work.

"missing components/ui/…"

The UI components that the ui key of aarshi.toml expects are not there. They are written by aarshi setup: shadcn installs them with button and button-group, and Base UI writes them from its own templates. Restore the missing file from another project created with the same ui value, or run aarshi setup in a new folder and copy the file.

Exit code 2 from aarshi status

The project cannot be read. The message on stderr says why: aarshi.toml is missing, unreadable, or contains an unknown key. Fix that file first, then run the check again.

The documentation does not open

aarshi docs writes the pages to a temporary folder and prints its path. If the browser does not open by itself, open index.html in the en or fr folder of that path by hand.

Still stuck?

Run aarshi status --json and keep the output: it lists every finding with its rule name, which is the first thing to share when you ask for help. The rules are listed in the CONVENTIONS.md file of the repository.