Troubleshooting

Updated

Most problems show up in one of two places: a repository's status in php artisan crate:repos:list, or a 401 from Composer.

Composer gets 401 Unauthorized

Crate gives the same 401 for every credential problem and does not say which one it is. Check, in order:

Composer has auth for the right host. The http-basic key in auth.json or COMPOSER_AUTH must be your Crate's host exactly, such as crate.example.com, without https://.
The credential is a registry credential: purpose crate.composer.consume, kind basic. A credential for anything else is refused.
The credential is still active. Revoked and expired credentials are refused. After a rotation, use the replacement.
For a personal credential, its owner is still an active member of Crate. Deactivating someone stops their personal credentials. Use an installation credential for servers and CI.

When an application was attached through Scalpels, CRATE_TOKEN in its environment holds the credential. Run php artisan crate:auth again after it changes. Do not print the auth file while you diagnose this.

A repository stays pending or building

Builds run on the queue. If statuses never change, the queue is not processing jobs. Check the managed queue in your Laravel Cloud environment. Do not set QUEUE_CONNECTION yourself; Cloud injects it.

Builds also run one at a time, so a build can wait behind a long one.

A repository is failed

The source token is wrong or expired. Replace it with the source-credential endpoint described in Serving packages, or remove the repository and add it again with a new --source-token.
Two repositories on the same host have different tokens. Crate uses one token per host during a build, so one repository can fail because the build used the other's token. Give them a token that can read both.
Git is missing. Satis needs git to read VCS repositories, in the runtime that runs the queue.
Satis is missing. The build step php artisan crate:install-satis must run during the Cloud build, after Composer installs the app. A successful build log says Satis was installed at satis-tool/bin/satis.
Another repository failed. A full build covers every repository, so one bad repository marks them all failed. Fix or remove the bad one and run php artisan crate:build.

Packages that were built before a failure keep being served from the bucket.

The package is missing from the registry

The name you registered must match the name in the package's composer.json. Remove it and add it under the right name.
php artisan crate:build vendor/package does nothing if that package is not registered. It still prints Dispatched Crate Satis build., so check the name with crate:repos:list.
You pushed a new tag since the last build. Crate does not rebuild on push; run php artisan crate:build vendor/package or wait for the daily build.

A dependency of my private package will not install

Crate serves only the packages you register, not their dependencies. Public dependencies come from Packagist. If a private package depends on another private package, register that one too.

Adding a repository fails

The repository name must match vendor/package ...: use a lowercase vendor/package name.
The repository [vendor/package] already exists.: it is already registered. Use crate:repos:list.
The repository type is invalid.: --type must be vcs, git or path.

The first Owner cannot sign in

php artisan create-admin creates the user in the environment you name with --environment=<environment-id>. Without it, the command asks where to create the user and defaults to your local database, which your deployed Crate cannot see. crate:* commands have no such option; they run where you type them.