Capacitor "must be run in a Capacitor project" in CI

By Daniel Zoghalchali·Latchkey

The Capacitor CLI locates the project by finding capacitor.config at the working directory. If CI runs cap from a subfolder, a monorepo package without the config, or before the config is created, the CLI refuses because it is not in a Capacitor project root.

What this error means

cap sync or cap add stops with a message that the command must be run at the root of a Capacitor project, with no native work attempted.

[error] Capacitor CLI needs to run at the root of a Capacitor project.
        Could not find the capacitor.config file in the current directory.

Common causes

cap ran from the wrong working directory

In a monorepo, the job did not change into the app package, so the CLI looked for capacitor.config where there is none.

The config file is absent or misnamed

capacitor.config.ts/json/js was not committed or has a typo in the name, so the CLI cannot detect the project.

How to fix it

Run cap from the package that holds the config

1. Set the working directory to the app package root.
2. Confirm capacitor.config exists there.
3. Then run cap commands.

defaults:
  run:
    working-directory: apps/mobile
steps:
  - run: npx cap sync

Commit a correctly named config

Ensure capacitor.config.ts, .js, or .json exists and is checked into the repo at the project root.

How to prevent it

• Pin the working-directory for cap steps in monorepos.
• Keep capacitor.config committed at the app root.
• Verify the file name matches a supported config extension.

Frequently asked questions

Related guides

References

• GitHub Actions documentation