Troubleshoot common problems

This page shows how to fix the problems people hit most. Each entry names the symptom, the usual cause, and the commands that resolve it. For the reasoning behind statuses and suspensions, read How billing works.

CLI and sign-in

command not found: acc

The CLI is not installed, or npm's global bin directory is not on your PATH.

npm install -g @alternatefutures/acc
acc --version

If the second command still fails, add npm's global bin directory to your PATH:

export PATH="$(npm config get prefix)/bin:$PATH"

acc login cannot open a browser

You are on a server or in a container. Use the email code flow instead:

acc login --email
acc whoami

The CLI prints its help instead of running a command

You ran a command that does not exist in acc, most often one from an old tutorial written for the retired af CLI (af sites deploy, af storage, af functions). See Retired af CLI guides for what replaced each one, and Command reference for the current commands.

"Authentication failed" or "Invalid token"

Your stored login expired, or AF_TOKEN holds a bad value.

acc logout && acc login          # interactive machines
echo -n "$AF_TOKEN" | wc -c      # CI: a copied token must have no trailing whitespace
acc pat create --name ci-runner  # issue a fresh token if needed

Commands act on the wrong project

The CLI uses your active project, or AF_PROJECT_ID if it is set.

acc whoami                       # shows the active project
acc projects switch <id>         # change it
acc services list -p <id>        # or name the project for one command

Deployments

The deployment stays in a waiting or creating state

A deployment waits for a provider to offer capacity. Most start within a few minutes. One that makes no progress for about 25 minutes is marked failed automatically, and you are not charged for it.

If it happens repeatedly, the request is hard to place:

acc regions                      # availability and price per region
acc regions --gpu h100           # for a specific GPU model

Then deploy again with a different region, smaller resources, or a different GPU model:

acc services deploy <id> --region us-west
acc services deploy <id> --gpu-model a100 --gpu-count 1

The deployment fails right away

Check the log and the deployment list:

acc services logs <id> --tail 200
acc deployments --service <id> --status failed

Common causes:

• The image cannot be pulled. The image name or tag is wrong, or the image is private. Images on GitHub Container Registry are private by default; make the package public in its GitHub settings.

• The wrong port. Pass the port your container listens on with --port.

• A required environment variable is missing. Templates list the variables they need. Set them with --env KEY=VALUE when you deploy, or afterwards:

  acc services env set <service> KEY VALUE
  acc services deploy <service>

A new image version does not show up after redeploying

Providers cache images by tag. A moving tag such as latest or main keeps serving the cached build, and the platform refuses those two tags when you change a service's image. Push a versioned tag (myimage:1.4.2) and deploy that.

The CLI refuses a template

Templates that start several services at once deploy from the web app only. Open Deploy at clouds.alternatefutures.ai and choose the template there.

The URL does not respond

The URL (https://<slug>-app.alternatefutures.ai) answers once the deployment is active and the container is listening on the port you exposed.

acc services info <id>           # status and URL
acc services logs <id> --tail 100
acc ssh <id>                     # a shell inside the running container

Suspended services and billing

A service shows as suspended

Your organization's credit wallet dropped below about one hour of total spend, so services were paused to protect the balance. Nothing was deleted.

acc billing balance
acc billing topup --crypto --amount 25   # or top up by card in the web app

Suspended services resume on their own after the topup. To stop paying for one instead, run acc services close <id>.

A deploy is refused for insufficient balance

Before every deploy the platform checks that the wallet covers at least one hour of everything you would then be running. Top up, or close services you no longer need, then deploy again.

A service stopped on its own

It reached a spend control you set: a total or monthly budget cap, or an auto-stop timer. acc services info <id> shows the stop reason. Deploy again with a higher cap, or with none:

acc services deploy <id> --spend payg

You cannot deploy after the trial

The 14-day trial has ended and the three-day grace period has passed. An owner or admin needs to choose a plan under Billing in the web app.

You cannot see Billing or Members in the web app

Those pages are shown to owners and admins only. Ask an owner to change your role or to do the task for you.

You cannot invite people

Invitations require an active paid subscription on the organization. Choose a plan first; see Manage billing and credits.

A card topup is not offered in the CLI

Card payments are web only. Open Billing in the web app. The CLI supports stablecoin topups with acc billing topup --crypto.

Custom domains

Custom domains are in early access. See Custom domains for the current state and the DNS records to use.

Still stuck

Run the failing command with --debug and keep the output, along with acc --version and the service id, when you ask for help.