Troubleshooting

Find the symptom or message you see, then follow its fix. For API status codes, see Error codes.

Connect your agent

Claude Desktop reports that the server disconnected

Server disconnected

Cause

Claude Desktop starts Pie’s connector with npx, which needs Node.js. The usual causes are a missing Node.js install, a wrong command path, or a Claude process that was never fully restarted.

Fix

1. Install Node.js, then open a terminal and run node --version to confirm it’s on your path.
2. On Windows, change npx to npx.cmd in the Pie block of your configuration.
3. If you point the configuration at a local command path, use forward slashes.
4. Quit Claude completely. Closing the window isn’t enough: on Windows, end the Claude process in Task Manager, then open Claude again.

You know it worked when Claude lists Pie among its connected tools. For the full configuration, see Connect your agent.

The agent connects but shows no data

Cause

The app has no runs yet, or the agent is talking to a different app than you expect.

Fix

1. Run at least one test in Pie.
2. Check that the app name in your configuration is the one you mean. A configuration entry is tied to one API key, and a key reaches one app.
3. Ask your agent: Fetch Pie and show me everything available.

You know it worked when the agent returns an overview of your app’s runs, coverage and issues.

The API key is rejected

Failed to validate API key: API key not found (in your agent)

Invalid API key (from the API)

Cause

The key was mistyped, cut short, or deleted in Settings > API Keys.

Fix

1. Create a new key. See Create an API key.
2. Paste it into your configuration without spaces or line breaks, and keep it inside the quotes.
3. Restart your AI platform.

You know it worked when the agent lists your app’s test cases.

The configuration file does not load

Cause

The JSON is invalid, or the block doesn’t match your platform. Cursor uses url and headers. VS Code uses servers. Both pass the key in the X-API-Key header.

Fix

1. Run the file through a JSON validator and fix missing commas, brackets and quotes.
2. Compare your block with the one for your platform in Connect your agent.
3. Restart the platform after you save.

You know it worked when the platform shows Pie as connected.

Runs

A run has not started yet

Preparing testing environment

Testing resources are at capacity. Your test is queued and will begin shortly.

Cause

The run is queued, and no Pie agent has picked it up yet. Pie shows the second message when a test has waited in the queue for a while.

Fix

1. Wait. The run starts when a Pie agent picks it up.
2. If the run still hasn’t started, contact support@pie.inc.

You know it worked when the status changes and step screenshots begin to appear.

A suite will not start a run

Cause

The suite has no test cases, and an empty suite can’t run.

Fix

1. Open the suite in Test Suites.
2. Select Add tests, choose the test cases and save.
3. Start the run again.

You know it worked when the run begins. See Organize tests into suites.

Sign-in and credentials

Pie cannot sign in to your app

Cause

The stored login doesn’t work. Common reasons are a wrong username or password, a locked or inactive account, or a password that changed after you stored it. Two-factor authentication fails when no fixed test code is stored. Codes sent by SMS don’t work.

Fix

1. Sign in yourself with the stored username and password.
2. If the account uses two-factor authentication, store a fixed test code in the Password / OTP / magic link field, and confirm the account is active.
3. Update the credential in Settings > Credentials Manager.
4. If your edge answers Pie with a challenge, a 403 or a 429, follow Allow Pie traffic safely.

You know it worked when a run gets past the login screen. See Manage credentials.

A test signs in as the wrong user

Cause

Pie picks the credential set on the test first, then the one set on the suite, then the app default. A test whose credential was deleted falls back to the suite’s credential first, then to the app default.

Fix

1. Check the Credential field under How it runs on the suite page.
2. Check the test’s steps for an @{credential-name} reference.
3. Check which credential carries the Default badge in Credentials Manager.

You know it worked when the run signs in as the role you intended.

GitHub and GitLab

GitHub cannot reach the repository

GitHub needs access to this repository

Cause

Pie Bot is installed, but the repository isn’t in the list of repositories it can read. Only someone who administers that GitHub account can add it.

Fix

1. Select Open GitHub App settings in the banner.
2. Ask the account administrator to add the repository to the Pie Bot installation.
3. Return to Pie and connect the repository again.

You know it worked when the Pie Bot sheet shows Connected.

The repository is connected to another app

This repository is connected to another Pie app

Cause

Each repository connects to one Pie app at a time.

Fix

1. Disconnect the repository from the other app in its Settings > Integrations, or choose a different repository.
2. Connect it to this app.

You know it worked when the banner no longer appears.

The install is waiting on an administrator

Waiting on your GitHub admin

Cause

Your GitHub organization requires approval for third-party apps, and the request hasn’t been approved yet.

Fix

1. Ask an organization admin to approve pie-pr-bot in the organization’s GitHub Apps settings.
2. After approval, return to Pie and connect the repository again.

You know it worked when the Pie Bot sheet shows Connected. Approval alone doesn’t finish the connection.

The connection fails with a generic message

Couldn't connect the repository

Couldn't read the GitHub installation

Cause

The install didn’t complete, or GitHub returned an installation Pie didn’t recognize. Nothing was changed.

Fix

1. Start the connection again from Settings > Integrations.
2. If it fails again, contact support@pie.inc with the repository name.

You know it worked when the Pie Bot sheet shows Connected.

GitLab shows no projects

No projects found, with a note that you need Maintainer access to connect a project.

Cause

The GitLab account you connected doesn’t have Maintainer access to any project Pie can list.

Fix

1. Ask a project owner to give your account Maintainer access.
2. Open the GitLab sheet, refresh the project list and select Connect next to the project.

You know it worked when the project shows Connected.

GitLab will not connect

Failed to connect GitLab

Cause

For self-managed GitLab, the host URL or personal access token is wrong, the token lacks the api scope, or a firewall blocks Pie.

Fix

1. Check the GitLab host URL and create a new token under Preferences > Access Tokens with the api scope.
2. If the instance sits behind a firewall, allowlist the addresses in the tooltip next to GitLab host URL.
3. Select Connect again.

You know it worked when the sheet shows Connected as your username. See Connect GitHub or GitLab.

PR tests

A run never reaches the changed feature

403, 429 or a bot challenge

Cause

A WAF rule, bot protection or rate limit answered Pie before the app did.

Fix

1. Create a narrow exception for Pie’s egress addresses on the preview environment.
2. Check API-gateway, user and tenant limits if the edge allows traffic but the API still returns 429.
3. Confirm the source IP in your logs matches the addresses Pie verified with you.

You know it worked when requests match your named Pie rule and none receives a challenge, 403 or 429. See Allow Pie traffic safely.

Pie signs in but the feature is missing

Cause

The feature flag resolves to its default value for Pie’s test identity, or a cached session holds an older value.

Fix

1. Give the test identity the flag values your pull request expects.
2. Check that the frontend and the backend evaluate the same flag.
3. Start from a clean session.

You know it worked when the changed feature shows on every run. See Make the changed feature visible.

The first run passes and later runs fail

Cause

A run changed or used up test data, and nothing reset it.

Fix

1. Reset the data between runs, or give each run its own namespace or record prefix.
2. Make the seed and reset commands safe to run twice.

You know it worked when three runs in a row start from the same state. See Prepare identity, access, and test data.

Team, keys and scripts

Invitations are refused

Too many invitations sent recently. Wait a few minutes and try again.

<email> was invited recently. Wait a few minutes before inviting them again.

<email> already has a pending invitation.

Cause

Pie limits how often invitations go out, and it doesn’t send a second invitation to an address that already has one pending.

Fix

1. Wait, then send the invitation again.
2. For a pending invitation, open the three-dot menu on its row in Team Management and select Resend invitation.

You know it worked when the address shows a Pending badge. See Invite your team.

A script placeholder is flagged

Issues (1)

Cause

The script uses a single-brace placeholder such as {phone_number}. The editor expects the double-brace form, {{phone_number}}, and flags the single-brace one.

Fix

1. Select Fix next to the issue, or Auto-fix all when there are several.
2. Select Test, enter a value for each parameter and select Run Test.

You know it worked when the editor lists the placeholder under Parameters Detected. See Use parameters in scripts.