> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find what is not set up with doctor, fix the errors Appeeky Spec prints, and answers to common questions about keys, accounts and undoing a push.

When a command fails, start with `doctor`. It lists what is set up, what is missing and the command that fixes it. The sections below cover the messages you are most likely to see, then common questions.

## Start with doctor

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec doctor
```

It checks Node, the spec, access to each store, the pulled listings, targets, the control group, `APPEEKY_API_KEY`, attribution, the GitHub workflows, the agent skills, the specialist agents and `.gitignore`. `✗` must be fixed, `!` is optional, and it exits 1 while anything is `✗`. Add `--json` to give the result to an agent or a script. See [Connect the stores](https://docs.appeeky.com/docs/spec-stores.md#check-the-setup) for sample output.

## Setup

**`No appeeky.spec.yaml found here or in a parent folder. Run appeeky-spec init first.`**
You are outside the app's folder. `cd` into it, pass `--cwd <dir>`, or run `npx @appeeky/spec init`.

**`appeeky.spec.yaml already exists in … Run appeeky-spec doctor to see what is set up.`**
`init` never overwrites a spec. To add only the GitHub workflows to an existing spec, run `init --ci`.

**`Give an App Store id or a Google Play package to set up the spec.`**
The guided setup did not find the app. Run it again and type the numeric App Store id or the Google Play package name when asked.

**A file path, then a field and a reason, for example `…/appeeky/store/app-store/en-US.yaml: (root): Unrecognized key(s) in object: 'subtitel'`**
A spec or listing file has a typo or a wrong value. Fix the field the message names. Common ones:

| Message | Fix |
| - | - |
| `Unrecognized key(s) in object` | A misspelled field name. See [Spec files](https://docs.appeeky.com/docs/spec-files.md) for the exact names |
| `Use a two-letter storefront code such as us, gb or tr` | A key under `targets` or `storefronts` is not a country code |
| `Use the package name, e.g. com.example.app` | `stores.googlePlay.packageName` is not a package name |
| `Invalid url` | `marketingUrl`, `supportUrl` or `video` is not a full URL |

## Store access

**`Could not start npx: … Save your App Store Connect API key once …`** (or `appstore`, `gps`)
The store CLI could not start. Check that Node 20+ and `npx` work, or install the CLI. Then save your key as the message shows. See [Connect the stores](https://docs.appeeky.com/docs/spec-stores.md#save-the-keys).

**`appstore … failed: …`** or **`gps … failed: …`**
The store said no. The end of the message is the store's own reason. Most often:

* The key is wrong, revoked, or the `.p8` path moved. Save the account again.
* The App Store key's role cannot write. Pushing needs **App Manager**.
* The Google Play service account is not invited in Play Console → **Users and permissions**, or has no access to this app.
* With several accounts, the wrong one is the default. Set `stores.appStore.account` or `stores.googlePlay.account`.

**`Set APPEEKY_API_KEY to use the hosted app-store gateway.`**
The spec or `--via` says `hosted`, but no key is set. Set `APPEEKY_API_KEY`, or switch `via` to `local` or `auto` and use your own keys.

**`… failed on asc-api.appeeky.com: …`** or **`Could not reach …`**
The hosted store connection failed. Check that the store is still connected in **Settings → Data sources** on appeeky.com and that your network is up. Or use your own keys.

**`The spec has no stores.appStore section.`**
A command needs a store the spec does not list. `screenshots pull` needs the App Store. Add the store under `stores:`.

## Pushing

**`Fix these first, or pass --force.`**
`check` found listing errors, usually a field over its limit. Fix them; `--force` pushes anyway and the store will likely reject the field.

**`Not a terminal: pass --yes to push.`**
`push` asks before it changes anything. In CI or a script, pass `--yes`.

**`Nothing to push.`**
The spec matches the store, or every change is blocked. Run `diff` to see which.

**`App Store Connect did not return the new version 2.5.0.`**
`--create-version` did not get a version back. Check in App Store Connect whether it exists. If it does, run `push` again without `--create-version`.

### A change is blocked

`diff` and `push` show `blocked:` under a change that cannot go live yet. `push` sends everything else.

| Message | Fix |
| - | - |
| `Name and subtitle change only with a new version. …` | Create the next App Store version, or pass `--create-version`, then push again |
| `keywords changes only with a new version (the current one is ready for sale). …` | Same: only promotional text changes on the live version |
| `This app has no App Store version yet.` | Create the first version in App Store Connect |
| `Adding de-DE needs a name in the spec.` | A new App Store locale needs `name` in its file |
| `A new Google Play language needs title, shortDescription, fullDescription in the spec.` | Fill in the fields it lists |

## Listing tools

**`No App Store listing for en-GB. Run appeeky-spec pull first.`**
`suggest` works on an App Store locale file. Pull it, or pass a `--locale` that exists.

**`Popularity missing for 4 keywords: …`**, or **`Appeeky API …: … (retry after 30s)`**
The Appeeky API allows 10 popularity lookups a minute. Spec stops when it hits the limit and keeps what it got for 7 days. Run `coverage` again in a minute to fill in the rest.

**`Set APPEEKY_API_KEY: …`**
Reviews, competitors, social, UGC from Appeeky and similar commands read data you connected in Appeeky. See [On your own keys](https://docs.appeeky.com/docs/spec-own-keys.md) for what runs without it.

**`No release 2026-11-02. See appeeky-spec log.`**
`revert` needs a release id, or the start of one. List them with `log`.

## FAQ

**Do I need an Appeeky account?**
No. With your own store keys you can pull, check, run coverage and suggest, diff, push, revert and verify on App Store ranks. An Appeeky API key adds keyword popularity, Google Play ranks, conversion and revenue in `verify`, and more. See [On your own keys](https://docs.appeeky.com/docs/spec-own-keys.md).

**Where are my keys kept?**
Saved accounts are in the store CLIs' config on your machine (`~/.config/appstore/`, `~/.config/gps/`). In CI they are repository secrets. With `via: hosted`, the store keys stay in Appeeky. Spec never writes keys into the repo. `.appeeky/` holds the cache and private data; keep it out of git.

**Can I undo a push?**
Yes. `revert <release-id>` puts the values from before the release back into the spec, then `push` sends them. A field that was empty before is cleared. Reverting App Store fields other than promotional text needs a new version, like any other change.

**Can I see what a push would do first?**
`diff` shows every change. `push --dry-run` shows the same and stops before it changes anything.

**Will push delete a locale or a field I did not list?**
No. Only the fields in your files are compared and pushed. Locales that exist only in the store are left alone. To clear a field, set it to `""`.

**Someone edited the listing in App Store Connect. What now?**
`diff` shows their edit as a change, and `push` would put your file's value back. To keep their edit, run `pull` (it overwrites your local files) and commit.

**Does push upload screenshots?**
No. See [Screenshots](https://docs.appeeky.com/docs/spec-screenshots.md).

Next: [Connect the stores](https://docs.appeeky.com/docs/spec-stores.md) · [Commands](https://docs.appeeky.com/docs/spec-commands.md) · [On your own keys](https://docs.appeeky.com/docs/spec-own-keys.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.