FAQ and troubleshooting

General

How is teriac different from tfenv, tfswitch or tgenv?

One tool covers Terraform, Terragrunt and OpenTofu, on macOS, Linux and Windows, with no sudo or admin rights. It reads the version files those tools use (.terraform-version, .tfswitchrc, .tfswitch.toml, .tgswitchrc, .tool-versions), so you can switch without touching your repos. And the same version rules drive teriac server.

How is teriac server different from Atlantis?

Both plan on pull requests and apply from comments. teriac server adds per-project permissions and approvals from your Git platform's teams, Terraform commands from the PR with their own permissions, policy checks with audited overrides, Terragrunt dependency handling, tamper-proof output, drift alerts with blame, and a dashboard with SSO, all in one container with SQLite.

Do I need the server to use the CLI, or the other way round?

No. They're independent. The server uses the CLI's install code internally, so versions are resolved the same way in both.

Which platforms does the server support?

GitHub.com and GitHub Enterprise Server (TERIAC_GITHUB_API_URL), through a GitHub App.

Is it free?

Yes. teriac is open source under the MIT license.

CLI problems

`terraform: command not found` after installing

Restart your terminal, or run exec $SHELL -l. teriac adds ~/.teriac/bin to your shell config on its first run, and only new shells read it. Then run teriac doctor.

`terraform` runs the wrong version

Another terraform comes first on your PATH, often Homebrew's.

teriac current        # shows which binary 'terraform' resolves to
teriac doctor         # checks PATH order
teriac upgrade        # moves ~/.teriac/bin back to the front

Or remove the other install: brew uninstall terraform.

The shell hook doesn't switch

Check the hook is in your shell config: grep teriac ~/.zshrc.
Open a new terminal after adding it.
Check the folder counts as a project: it needs a version file, a .tool-versions line, a Terragrunt file, or a *.tf file.
Run teriac auto-switch by hand to see its output.

`latest` fails for OpenTofu or Terragrunt

Their version lists come from the GitHub API, which allows 60 anonymous requests an hour. Set GITHUB_TOKEN, or install an exact version, which doesn't need the list: teriac install 1.8.0 -p tofu.

`SHA256 mismatch`

The download doesn't match the release's published checksum. teriac stops and installs nothing. Try again; if it keeps happening, check your mirror or proxy isn't changing files.

`signature` errors after upgrading to 0.2.0

teriac checks each download's checksum file against the vendor's PGP signature. If you install from a mirror that doesn't copy the .sig / .gpgsig files, either add them to the mirror or set TERIAC_VERIFY_SIGNATURES=false (config.verifySignatures: false in the Helm chart). See signed downloads.

I'm on Apple Silicon and an old version has no arm64 build

Install the Intel build: teriac install 0.12.31 --arch amd64. It runs under Rosetta.

I installed with `sudo`

Setup skips sudo runs so ~/.teriac is never owned by root. Run any teriac command as yourself once. If ~/.teriac already belongs to root: sudo chown -R "$USER" ~/.teriac.

Where are my versions? How do I start over?

In ~/.teriac/store/ (or $TERIAC_HOME/store/). To start over, delete ~/.teriac and run teriac again.

Server problems

The server won't start: "No repos allowed"

Set TERIAC_REPO_ALLOWLIST (e.g. github.com/acme/*) or list repos in repos.yaml. A server that would run code from any repo refuses to start.

The server won't start: a `repos.yaml` error

The message names the file and the key, e.g. repos[0].projects[1].match is required. Fix that line. If you set TERIAC_REPOS_CONFIG, the file must exist and be readable by uid 10001.

The server won't start: a backup error

With TERIAC_BACKUP_ENABLED=true, a wrong backup setting stops the server with one error that names it (a bad cron, a bucket with / in it, a channel missing from repos.yaml).

On an empty volume, the server also refuses to start when it can't read the bucket, so it never starts empty by mistake. Check the bucket name and the bucket permissions. To start empty on purpose, set TERIAC_BACKUP_ENABLED=false for that start.

Nothing happens on a pull request

In the GitHub App's Advanced tab, check Recent deliveries. A 401 means the webhook secret is wrong; a timeout means GitHub can't reach the server.
Check the App is installed on the repo and subscribed to Pull request, Issue comment and Check run.
Check the repo matches the allowlist (github.com/owner/name).
Draft PRs aren't planned unless plan_drafts: true. Autoplan can be off (autoplan: false).
Check the server's logs (TERIAC_LOG_LEVEL=debug for more).

A project wasn't planned

teriac plans projects whose files, modules or Terragrunt includes changed. For other inputs, such as Lambda source, add a teriac:watch. Or plan it by hand: teriac plan -p <project>.

`git@github.com` module sources fail

Since 0.2.1 the image has no SSH client. Use git::https:// sources, and give git a token for private modules, as shown in private modules.

teriac can't open fix PRs, or team rules don't work

Check the GitHub App's permissions: drift fix PRs need Contents: read & write, and team: rules need organization Members: read. After changing permissions, an org owner must accept them under Installed GitHub Apps.

"locked by #123"

Another PR holds the project's lock. Apply or teriac unlock there, merge or close it, or ask an admin to release the lock from the dashboard.

Apply is refused

The reply says why. Common reasons:

Reply	Fix
Missing approvals	Get the approvals the project needs, on the current commit
PR is not mergeable / behind the base branch	Resolve conflicts, update the branch
Re-plan first	A newer commit, or a dependency was applied: comment `teriac plan`
Planned with mock outputs	Apply the Terragrunt dependency first
Policy finding	Fix the code, or ask someone in `override` to apply with `--override`
The author can't apply	The two-person rule is on: ask a teammate
Bare `teriac apply` refused	Name the project: `teriac apply -p <project>`

No spinner with `TERIAC_PROGRESS_REPLY`

GitHub loads the spinner image itself, so it needs a public https TERIAC_PUBLIC_URL. On a private or http URL, teriac falls back to the 👀 reaction.

Dashboard sessions end after a restart

Set TERIAC_SESSION_SECRET (32+ characters). The Helm chart does this for you.

Your groups must be in TERIAC_OIDC_ADMIN_GROUPS or TERIAC_OIDC_ALLOWED_GROUPS, and the ID token must carry them in the groups claim (or set TERIAC_OIDC_GROUPS_CLAIM).

Still stuck?

Open an issue at github.com/marcdomain/teriac/issues with the output of teriac doctor (CLI) or the server's logs around the problem.