Troubleshooting

Common issues and their solutions when deploying Pixelflare.

Terraform Issues

Authentication Failed

Error: Error: failed to fetch account: ...

Solution:

• Verify your CLOUDFLARE_API_TOKEN has the correct permissions
• Ensure your CLOUDFLARE_ACCOUNT_ID is correct
• Check token hasn't expired

Resource Already Exists

Error: Error: resource already exists

Solution:

terraform import <resource_type>.<name> <id>

Worker Deployment

Wrangler Command Not Found

Solution:

pnpm install -g wrangler
# or
npx wrangler

Invalid Configuration

Check your wrangler.toml was generated correctly:

cat packages/api/wrangler.production.toml

Access & Authentication

Unable to Login

Symptom: Redirects to login repeatedly

Possible causes:

1. GitHub OAuth callback URL incorrect
2. Access policy too restrictive
3. CF_ACCESS_AUD mismatch

Solution:

# Verify callback URL
terraform output github_callback_url

# Check Access audience
terraform output cf_access_aud

403 Forbidden

Check Cloudflare Access rules allow your email/domain.

Runtime Issues

Images Not Loading

1. Check R2 bucket has images
2. Verify custom domain is configured
3. Check Worker logs: wrangler tail

Upload Failing

Error: "Invalid upload token"

Solution:

# Verify secrets are set
wrangler secret list

# Reset upload token secret
openssl rand -hex 32 | wrangler secret put UPLOAD_TOKEN_SECRET

Database Issues

Migrations Not Applied

# Check migration status
wrangler d1 migrations list pixflare-db-production

# Apply migrations
wrangler d1 migrations apply pixflare-db-production

Getting Help

Still stuck?

1. Check GitHub Issues
2. Search Discussions
3. Open a new issue with details about your problem