Factory
Pages

Troubleshooting

#new-project

#missing: jq

A tool is missing. Install it, and run the command again. See Installation and setup.

#exists. Choose another name or folder.

The folder is there. Use another name, or --dir.

#Lint fails on the new app

The app is in place, with no remote. Fix the lint error in the app, then finish by hand. You can also delete the folder and run the command again.

#CI and the review

#Cannot connect acme-org/acme

The AWS connection cannot see the repository. Add the repository to the AWS Connector and to the review app. The command prints both links. Then run connect-repo again.

#The stack fails on AWS::CodeConnections::Connection

The region has no CodeConnections. af-south-1 is one of them. Use another region, and change FACTORY_REGION.

#A push does not run the review

This is on purpose, because each review uses your Claude plan. The review runs when a pull request opens or reopens. Press Review in the panel, or run:

review-pr acme 3

#ci/codebuild does not appear

Webhook builds run only for pull requests from a trusted GitHub user. Add the numeric user id to FACTORY_TRUSTED_ACTORS, and run connect-repo again.

#flow/review fails with no comments

Read the log of the build in the CodeBuild console. Three causes are common.

  • The Claude token expired. Store a new one, with --overwrite on the same command. See Store the Claude token.
  • The repository is not on the review app. The build stops when it asks for a token.
  • The project was made by an older factory-kit. Run connect-repo again, with --app-path apps/api for a monorepo.

#The Review button says the AWS session expired

Run aws sso login. The Review button uses the AWS session of your terminal.

#This account has no Flow licence

This message comes from the hosted Flow App. factory-kit does not use that app. Remove it from the repository.

#The panel

#A card does not move after a build

The panel updates the hub from GitHub each minute. Press Refresh to update it now.

#Cannot update the hub from GitHub

This shows at the top of the panel. Your hub has a commit that is not on GitHub, or a change that conflicts. Run git status in the hub, then commit and push, or remove the change.

#A session stops at once with a git error

Each session first updates the hub from GitHub, and it stops when it cannot. Fix it in the same way.

#A button only says that the session is running

The session of that step is still open. It waits at its prompt after it finishes. Type /exit in it, then press the button again.

#is not a product hub: it has no factory.json

The tab points at another folder. Open the tab for the hub again. See The Factory panel.

#The panel has no pull requests

Run gh auth status. The panel reads the repositories from mars.yaml and factory.json, and it refreshes each minute. Press Refresh to read them now.

#unknown kind: explore

The hub was made by an older factory-kit. Copy scripts/factory-session.sh and .claude/skills/explore/ from hub/ of factory-kit.

#Sessions

#permission denied for git remote

A session tried a command that the settings of the hub deny. The session continues with other commands. You can ignore it.

#A session offers to do the next step

Say no. Type /exit, and start the next step from the panel. Each step must start clean.