Troubleshoot the Cloider container registry

View as Markdown Open in Claude Open in ChatGPT

This page lists the errors people hit most with the Cloider Container Registry, what causes each one, and how to fix it. Errors are grouped by where you see them: logging in, pushing, pulling, Kubernetes, the dashboard and API, and the CLI.

Quick checks

Most registry problems come down to one of these. Check them first:

Host: the registry is registry.cloider.com, and image names are registry.cloider.com/<project>/<repository>:<tag>, all lowercase.
Username: your account's registry username (shown on a project's Overview tab and with every token), not your email address.
Password: a registry token's secret, not your Cloider password and not an API token (cldr_...).
Token scope: the token covers the project in the image name (All projects or the project by name).
Token permission: pushing needs Pull & push. Pull only tokens can't push or delete.
Token expiry: the token isn't Expired and wasn't deleted.
One login per host: docker keeps one login for registry.cloider.com. Logging in with another token replaces the first, so the last login wins.

# Which login does docker use for the registry?
grep -A3 '"registry.cloider.com"' ~/.docker/config.json

# Does the project exist, and is it Ready?
cloider registry get acme

# Which tokens exist, with their projects, permission and expiry?
cloider registry token list

`unauthorized: authentication required` or `incorrect username or password` on `docker login`

docker login fails when the username and secret don't match a valid token:

The username isn't your registry username. Copy it from the project's Overview tab (Quick Start) or from cloider registry token list.
The secret was mistyped or truncated. Secrets are long; paste them with --password-stdin rather than typing them.
The token was deleted or has expired. Create a new one.
You used an API token (cldr_...) or your account password. The registry only takes registry token secrets.

The fastest fix on your own machine:

cloider registry login

Username with `$` gets mangled

Some older tokens log in with a username that contains $. In double quotes or unquoted, your shell expands $... as a variable. Copy the username from the token list and put it in single quotes:

docker login registry.cloider.com -u '<username>'

`Error saving credentials: error storing credentials`

Docker's credential helper (credsStore in ~/.docker/config.json, such as osxkeychain, desktop or pass) failed. Unlock the keychain, fix the helper, or remove the credsStore line to store the login in the file.

`cloider registry login` errors

Error	Fix
`docker isn't on the PATH, log in with the command above`	The token was created and its `docker login` command printed. Run it by hand, or with `podman login`
`docker login exited with code N`	Docker refused the login. The new token was deleted and your previous login is unchanged. Check that the Docker daemon is running
`--expires-days is 0 for never, or 1 to 3650`	Use a value in that range
`You have read-only access to this account, you can not create registry tokens!`	The CLI's API token is read-only or your role is Restricted. Log in with a token that can write, or ask an Owner or Admin for a registry token
`Choose a project that is ready, or create one first`	The account has no project yet. Run `cloider registry create <name> --wait`

Push errors

`denied: requested access to the resource is denied`

The login works but the token may not push here:

The token is Pull only. Use a Pull & push token, or change the token's permission in the dashboard or with cloider registry token update <token> --read-only=false.
The token doesn't cover the project named in the image. Check the image name's second segment and the token's Projects.
The image name has a typo in the project, for example registry.cloider.com/acem/api. Pushing never creates a project; create projects first.

`unauthorized: unauthorized to access repository` on push or pull

The client isn't logged in for this host, or the login is for a token that expired, was deleted, or doesn't cover the project. Run docker login registry.cloider.com again with a current token.

Push of an existing tag is refused as immutable

The tag already exists and is protected by the project's Immutable tags setting or an immutability rule. Immutable tags can't be pushed over:

Push a new, unique tag (a version or commit SHA).
Or narrow the rule so moving tags like latest, main or buildcache stay mutable.

See Immutable tags.

Push refused because of the storage quota

A push that would take the project past its storage limit is refused, and docker push fails with a quota error. Check the project's storage:

cloider registry get acme

Output
Storage:       4.9 GiB of 5 GiB

Then delete images you don't need, set up a retention policy, or raise the limit (up to 20 GB) in the project's Settings tab or with cloider registry set acme --storage-limit 10.

`name unknown` or `repository name must be lowercase`

Repository names are lowercase, with ., _, __, - and / as separators. registry.cloider.com/acme/MyApp is invalid; use registry.cloider.com/acme/my-app.

Push hangs or retries on large layers

Very large layers (several GB) are slow over poor connections. Use smaller images (multi-stage builds, slim bases) and push from CI close to a good network. Docker retries failed layer uploads automatically.

Pull errors

`manifest unknown` or `not found`

The tag or digest doesn't exist in that repository:

Check the exact names: cloider registry images acme api.
The tag may have been removed, moved, or deleted by a retention run. Check the project's Retention Runs.
An untagged image may have been removed by the nightly cleanup.
For a multi-platform image, check that it was pushed (docker buildx build --push), not only built locally.

`no matching manifest for linux/amd64 in the manifest list entries`

The image was built for another platform, often linux/arm64 on an Apple silicon Mac. Rebuild with --platform linux/amd64, or build a multi-platform image with buildx. See Build multi-platform images.

`exec format error` when the container starts

Same cause: the image's CPU architecture doesn't match the machine. Rebuild for the right platform.

The project's Public pulls setting is off, or the image is in another, private project. Check Access on the project's Overview tab. If a stale or wrong login is stored for registry.cloider.com, it is used even for public pulls; run docker logout registry.cloider.com.

Kubernetes errors

`ImagePullBackOff` or `ErrImagePull`

Read the events of the pod:

kubectl describe pod <pod> -n <namespace> | grep -A10 Events

Event message	Fix
`unauthorized` or `authentication required`	The pull Secret is missing, is in another namespace, isn't listed in `imagePullSecrets`, or holds an expired or deleted token. Recreate it with `-n <namespace>`
`denied`	The token in the Secret doesn't cover the project
`manifest unknown` / `not found`	Wrong image name or tag
`no match for platform in manifest`	Build the image for the nodes' platform

The pull secret command from the dashboard and the CLI has no namespace, so it creates the Secret in default. Add -n <namespace>. See Use with Kubernetes and Pull private images.

Running pods are fine, new pods fail

Pods that already pulled an image keep running, but new pods (scaling, a new node, a restart) pull again. If the token was deleted or expired since, new pulls fail. Create a new token and replace the Secret.

Dashboard and API errors

Message	Cause and fix
`This project name is already taken`	Project names are shared by every account. Choose another
`Free plan users can not create more than one project. UPGRADE NOW!`	Upgrade on Billing
`The project must be ready to browse its images.`	Wait until the project is Ready. A Failed project should be deleted and created again
`Couldn't reach the registry, try again in a moment!`	A temporary problem. Retry
`Couldn't read the project, try again in a moment!`	The live storage summary couldn't be read. Retry
`A tag immutability rule protects this tag. Disable the rule in the Policy tab to delete it.`	See Immutable tags
`This image is in use by another image in the repository, delete that one first.`	The image belongs to a multi-platform index. Delete the index instead
`It doesn't exist any more, reload and try again!`	It was deleted meanwhile. Reload
`Another change to this project is in progress, try again in a moment!`	Two changes ran at once. Retry
`This project holds your apps' images and is managed by Cloider...`	The apps project's images, policies and the project itself are managed by Cloider
`This project's policies were changed outside the dashboard, contact support to edit them.`	Contact support
`You have read-only access to this account, ...`	Your role is Restricted or your API token is read-only
`The container registry isn't available at the moment!`	Creating projects is temporarily unavailable. Try later or contact support

API errors come as JSON with HTTP status 400 (or 403, 404):

{"errors": {"name": ["This project name is already taken"]}, "data": null}

Messages that aren't about one field are under "_". See API errors.

CLI exit codes

Exit code	Meaning
`1`	Error
`2`	Usage error, for example a missing `--yes` without a terminal
`3`	Not logged in, or the API token was revoked. Run `cloider login`
`4`	Not found, for example a project, token, image or rule that doesn't exist
`5`	Forbidden, a read-only API token

cloider --debug ... logs every API request to stderr (never the token). See Output and scripting.

buildx and multi-platform images

Extra `unknown/unknown` entries

buildx adds provenance attestations to multi-platform images as manifests with the platform unknown/unknown. They aren't runnable images, so the dashboard and the CLI leave them out of the Platforms column. Build with --provenance=false if you don't want them.

A platform image can't be deleted

The images that make up a multi-platform index can't be deleted while the index points to them: This image is in use by another image in the repository, delete that one first. Delete the index entry, which lists all platforms.

Builds are slow on CI

Building arm64 on an amd64 runner uses QEMU emulation, which is slow. Build only the platforms you run, use native runners per platform, or cache layers in the registry with --cache-to type=registry,...,mode=max.

Rate limits

Pushing base images you use often (for example node, python or nginx) into your own project means your builds and clusters pull them from registry.cloider.com instead of Docker Hub, and so aren't subject to Docker Hub's pull rate limits:

skopeo copy --all docker://docker.io/library/node:22-alpine docker://registry.cloider.com/acme/node:22-alpine

Calls to the Cloider API from the dashboard, CLI, Terraform and MCP have their own limits; see API rate limits.

Still stuck?

Open a support request with the project name, the full image name, the exact command and its output. Never include a token's secret.

Quick checks​

Login errors​

unauthorized: authentication required or incorrect username or password on docker login​

Username with $ gets mangled​

Error saving credentials: error storing credentials​

cloider registry login errors​

Push errors​

denied: requested access to the resource is denied​

unauthorized: unauthorized to access repository on push or pull​

Push of an existing tag is refused as immutable​

Push refused because of the storage quota​

name unknown or repository name must be lowercase​

Push hangs or retries on large layers​

Pull errors​

manifest unknown or not found​

no matching manifest for linux/amd64 in the manifest list entries​

exec format error when the container starts​

Pulls from a public project ask for a login​

Kubernetes errors​

ImagePullBackOff or ErrImagePull​

Running pods are fine, new pods fail​

Dashboard and API errors​

CLI exit codes​

buildx and multi-platform images​

Extra unknown/unknown entries​

A platform image can't be deleted​

Builds are slow on CI​

Rate limits​

Still stuck?​

Next steps​