# Troubleshoot common problems (/troubleshooting) 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](/guides/how-billing-works). ## CLI and sign-in [#cli-and-sign-in] ### `command not found: acc` [#command-not-found-acc] The CLI is not installed, or npm's global bin directory is not on your `PATH`. ```bash npm install -g @alternatefutures/acc acc --version ``` If the second command still fails, add npm's global bin directory to your `PATH`: ```bash export PATH="$(npm config get prefix)/bin:$PATH" ``` ### `acc login` cannot open a browser [#acc-login-cannot-open-a-browser] You are on a server or in a container. Use the email code flow instead: ```bash acc login --email acc whoami ``` ### The CLI prints its help instead of running a command [#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](/legacy) for what replaced each one, and [Command reference](/cli/commands) for the current commands. ### "Authentication failed" or "Invalid token" [#authentication-failed-or-invalid-token] Your stored login expired, or `AF_TOKEN` holds a bad value. ```bash 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 [#commands-act-on-the-wrong-project] The CLI uses your active project, or `AF_PROJECT_ID` if it is set. ```bash acc whoami # shows the active project acc projects switch # change it acc services list -p # or name the project for one command ``` ## Deployments [#deployments] ### The deployment stays in a waiting or creating state [#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: ```bash 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: ```bash acc services deploy --region us-west acc services deploy --gpu-model a100 --gpu-count 1 ``` ### The deployment fails right away [#the-deployment-fails-right-away] Check the log and the deployment list: ```bash acc services logs --tail 200 acc deployments --service --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: ```bash acc services env set KEY VALUE acc services deploy ``` ### A new image version does not show up after redeploying [#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 [#the-cli-refuses-a-template] Templates that start several services at once deploy from the web app only. Open **Deploy** at [clouds.alternatefutures.ai](https://clouds.alternatefutures.ai) and choose the template there. ### The URL does not respond [#the-url-does-not-respond] The URL (`https://-app.alternatefutures.ai`) answers once the deployment is active and the container is listening on the port you exposed. ```bash acc services info # status and URL acc services logs --tail 100 acc ssh # a shell inside the running container ``` ## Suspended services and billing [#suspended-services-and-billing] ### A service shows as suspended [#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. ```bash 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 `. ### A deploy is refused for insufficient balance [#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 [#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 ` shows the stop reason. Deploy again with a higher cap, or with none: ```bash acc services deploy --spend payg ``` ### You cannot deploy after the trial [#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 [#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 [#you-cannot-invite-people] Invitations require an active paid subscription on the organization. Choose a plan first; see [Manage billing and credits](/guides/billing). ### A card topup is not offered in the CLI [#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] Custom domains are in early access. See [Custom domains](/guides/custom-domains) for the current state and the DNS records to use. ## Still stuck [#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.