Troubleshooting
Search for your error message below, or browse by category. If your error is not listed, open a GitHub issue.
Installation errors
Section titled “Installation errors””credctl: command not found”
Section titled “”credctl: command not found””Cause: credctl binary is not in your PATH.
Solution:
If you installed via Homebrew, restart your shell:
exec $SHELLIf you installed from GitHub Releases, add the binary location to your PATH:
echo 'export PATH="/Applications/credctl.app/Contents/MacOS:$PATH"' >> ~/.zshrcsource ~/.zshrcmacOS Gatekeeper blocks the binary
Section titled “macOS Gatekeeper blocks the binary”Cause: The binary was downloaded from GitHub Releases and macOS has not verified the signature.
Solution: Right-click the application, select Open, then click Allow in the dialogue. Alternatively, use the Homebrew installation method which handles signing automatically.
Initialisation errors
Section titled “Initialisation errors””Secure Enclave is not available on this device”
Section titled “”Secure Enclave is not available on this device””Cause: Running on a Mac without a Secure Enclave (pre-2016 Intel Mac) or a non-macOS platform.
Solution: credctl requires macOS with a Secure Enclave:
- Apple Silicon Macs (M1, M2, M3, M4)
- Intel Macs with T2 chip (MacBook Pro 2018+, MacBook Air 2018+, Mac mini 2018, iMac Pro, Mac Pro 2019)
“Device identity already exists.”
Section titled ““Device identity already exists.””Cause: Running credctl init when a key already exists in the Secure Enclave.
Solution: Check your existing identity with credctl status. To replace it, use --force:
credctl init --force”failed to create config directory”
Section titled “”failed to create config directory””Cause: Permission issue creating ~/.credctl/.
Solution: Check that your home directory is writable and that ~/.credctl/ does not already exist as a file:
ls -la ~/.credctlIf it exists as a file, remove it and re-run credctl init.
Authentication errors
Section titled “Authentication errors””device not initialised — run ‘credctl init’ first”
Section titled “”device not initialised — run ‘credctl init’ first””Cause: Running credctl auth before credctl init, or ~/.credctl/config.json is missing or empty.
Solution:
credctl initcredctl setup aws --policy-arn arn:aws:iam::123456789012:policy/YourPolicy“AWS not configured — run ‘credctl setup aws’ or configure manually”
Section titled ““AWS not configured — run ‘credctl setup aws’ or configure manually””Cause: The aws block in ~/.credctl/config.json is missing or incomplete.
Solution:
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/YourPolicyOr manually add role_arn, issuer_url, region, and s3_bucket to the aws block in ~/.credctl/config.json. See the configuration reference.
”assume role” error (access denied on AssumeRoleWithWebIdentity)
Section titled “”assume role” error (access denied on AssumeRoleWithWebIdentity)”Cause: The IAM role trust policy does not reference the OIDC provider, the audience does not match, or the OIDC documents are not published.
Solution:
-
Verify OIDC documents are accessible at the issuer URL:
Terminal window curl $(cat ~/.credctl/config.json | python3 -c "import sys,json; print(json.load(sys.stdin)['aws']['issuer_url'])")/.well-known/openid-configuration -
Check the IAM role trust policy references the correct OIDC provider ARN in the AWS Console.
-
Re-run setup to re-publish OIDC documents if needed:
Terminal window credctl setup aws --policy-arn <your-policy-arn>
Touch ID authentication failed
Section titled “Touch ID authentication failed”Cause: You cancelled the Touch ID prompt, or Touch ID is not available (lid closed, external keyboard without Touch ID).
Solution: Retry the command and approve the Touch ID prompt. With the default biometric policy (--biometric=any), macOS falls back to passcode entry if Touch ID is unavailable.
If Touch ID is consistently unavailable (e.g., Mac mini, laptop in clamshell mode), you can permanently disable the Touch ID requirement by reinitialising with:
credctl init --force --biometric=noneTouch ID not prompted during credctl auth
Section titled “Touch ID not prompted during credctl auth”Cause: The device key was created with --biometric=none, which disables user verification for signing operations.
Solution: If you want Touch ID to be required, reinitialise with a biometric policy:
credctl init --force --biometric=anyThis destroys the existing key and creates a new one with Touch ID enabled. You will need to re-register the new public key with your cloud providers (credctl setup aws, credctl setup gcp).
CloudFormation deployment errors (—cloudfront only)
Section titled “CloudFormation deployment errors (—cloudfront only)”“CloudFormation deploy failed”
Section titled ““CloudFormation deploy failed””Cause: Insufficient IAM permissions or resource conflicts when using credctl setup aws --cloudfront.
Solution: You need permissions to create CloudFormation stacks, S3 buckets, CloudFront distributions, IAM OIDC providers, and IAM roles. Check the CloudFormation events in the AWS Console for the specific error.
”S3 bucket already exists”
Section titled “”S3 bucket already exists””Cause: S3 bucket names are globally unique. Another account owns a bucket with the same name.
Solution: Use a custom bucket name:
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/YourPolicy --bucket my-unique-bucket-nameConfiguration errors
Section titled “Configuration errors””failed to read config”
Section titled “”failed to read config””Cause: ~/.credctl/config.json is malformed JSON or has incorrect permissions.
Solution: Check the file is valid JSON:
python3 -m json.tool ~/.credctl/config.jsonCheck permissions:
ls -la ~/.credctl/config.jsonThe file should be 0600 (-rw-------).
Credential helper errors
Section titled “Credential helper errors”AWS CLI: “Error when retrieving credentials from custom-process”
Section titled “AWS CLI: “Error when retrieving credentials from custom-process””Cause: The credential_process entry in ~/.aws/config is incorrect.
Solution: Verify the entry uses an absolute path:
[profile credctl]credential_process = /Applications/credctl.app/Contents/MacOS/credctl authFind the full path with:
which credctlTerraform: “No valid credential sources found”
Section titled “Terraform: “No valid credential sources found””Cause: Terraform is not using the correct AWS profile.
Solution: Set the AWS_PROFILE environment variable:
export AWS_PROFILE=credctlterraform planOr specify the profile in your Terraform provider block:
provider "aws" { profile = "credctl"}General diagnostic steps
Section titled “General diagnostic steps”If none of the above errors match, run through this checklist:
- Check version:
credctl version - Check device identity:
credctl status - Check configuration:
cat ~/.credctl/config.json | python3 -m json.tool - Test authentication:
credctl auth - Check directory permissions:
ls -la ~/.credctl/ - Check credential_process entry:
cat ~/.aws/config - Verify OIDC endpoint:
curl <issuer_url>/.well-known/openid-configuration
Getting help
Section titled “Getting help”- GitHub Issues — report a bug
- GitHub Discussions — ask a question
When reporting issues, include:
credctl versionoutput- macOS version (
sw_vers) - The full error message
- Steps to reproduce