Pixelflare

Appearance

Troubleshooting ​

Common issues you might encounter when deploying and running Pixelflare, with their solutions.

Deployment Errors ​

Missing Required Tools ​

Error: command not found: terraform (or wrangler, jq, curl)

Cause: Required CLI tools not installed.

Solution:

bash
# macOS
brew install terraform wrangler jq curl

# Linux (Debian/Ubuntu)
sudo apt install jq curl
npm install -g wrangler

# Install Terraform from https://terraform.io/downloads

Missing Environment Variables ​

Error: CLOUDFLARE_API_TOKEN not set or is placeholder

Cause: .env file missing or contains placeholder values.

Solution:

  1. Copy .env.example to .env
  2. Fill in CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and DOMAIN
  3. Get API token from Cloudflare Dashboard

Invalid API Token ​

Error: API token validation failed or Error: failed to fetch account

Cause: API token is invalid, expired, or has insufficient permissions.

Solution:

  1. Create new API token with all required permissions (see deployment guide)
  2. Update CLOUDFLARE_API_TOKEN in .env
  3. Ensure token includes Account and Zone permissions

Domain Not Found in Cloudflare ​

Error: Domain example.com not found in Cloudflare account

Cause: Domain hasn't been added to your Cloudflare account.

Solution:

  1. Go to Cloudflare Dashboard
  2. Add your domain
  3. Update nameservers at your domain registrar
  4. Wait for DNS to propagate (status should be "Active")

Terraform State Lock ​

Error: Error acquiring the state lock

Cause: Previous Terraform run didn't complete or crashed.

Solution:

bash
cd terraform
terraform force-unlock <lock-id>

Replace <lock-id> with the ID shown in the error message.

Resource Already Exists ​

Error: Error: resource already exists

Cause: Terraform trying to create a resource that already exists from previous run.

Solution:

bash
# Import existing resource
terraform import <resource_type>.<name> <id>

# Example for Worker script:
terraform import module.workers.cloudflare_workers_script.api <script-id>

Terraform Not Initialized ​

Error: Error: Could not load plugin or Terraform has not been initialized

Cause: Terraform providers haven't been downloaded.

Solution:

bash
cd terraform
terraform init

Terraform Version Mismatch ​

Error: Error: Unsupported Terraform Core version

Cause: Terraform version is too old (requires >= 1.5.0).

Solution:

bash
# Check version
terraform version

# Upgrade Terraform
# macOS: brew upgrade terraform
# Linux: Download from https://terraform.io/downloads

Cloudflare Provider Version Issues ​

Error: Error: Failed to query available provider packages

Cause: Cloudflare provider version incompatible or download failed.

Solution:

bash
cd terraform
rm -rf .terraform .terraform.lock.hcl
terraform init

Invalid Environment Variable ​

Error: Environment must be one of: dev, staging, production

Cause: ENVIRONMENT variable has invalid value in .env.

Solution: Set ENVIRONMENT=production (or dev/staging) in .env file.

Invalid Auth Mode ​

Error: auth_mode must be one of: none, cloudflare, authjs

Cause: AUTH_MODE variable has invalid value.

Solution: Set AUTH_MODE=cloudflare (or authjs/none) in .env file.

Queues Without Paid Plan ​

Error: Queues created but not working, or queue consumer errors.

Cause: Cloudflare Queues require Workers Paid plan ($5/month).

Solution:

  1. Upgrade to Workers Paid in Cloudflare Dashboard
  2. Or disable queues: Set ENABLE_QUEUES=false in .env and redeploy
  3. Note: Without queues, image variants won't be generated automatically

Terraform Worker Script Read Error ​

Error: Error reading worker script from API: unexpected EOF

Cause: Intermittent Cloudflare API issue during state refresh.

Solution: Simply retry the deployment - this is a transient error:

bash
make deploy

Wrangler Config Not Found ​

Error: Error: Wrangler config not found: packages/api/wrangler.production.toml

Cause: Terraform didn't generate wrangler configs or step was skipped.

Solution:

bash
# Regenerate configs
./scripts/tasks/05-generate-wrangler-config.cjs production

Database Migrations Failed ​

Error: Migrations not applied or schema errors.

Cause: D1 database created but migrations didn't run.

Solution:

bash
# Check migration status
wrangler d1 migrations list pixflare-production-db --config packages/api/wrangler.production.toml

# Apply migrations
wrangler d1 migrations apply pixflare-production-db --config packages/api/wrangler.production.toml --remote

Secrets Not Set ​

Error: Worker deployment succeeds but app doesn't work properly.

Cause: Required secrets weren't uploaded to Workers.

Solution:

bash
# Re-run secrets setup
./scripts/tasks/12-set-secrets.sh production

# Verify secrets are set
wrangler secret list --config packages/api/wrangler.production.toml

Pages Deployment Failed ​

Error: Frontend build or deployment fails.

Cause: Build errors, missing dependencies, or Pages configuration issues.

Solution:

bash
# Check build locally first
cd packages/frontend
pnpm build

# View deployment logs
wrangler pages deployment tail --project-name pixflare-frontend

Runtime Errors ​

Unable to Login / Redirect Loop ​

Error: Clicking "Sign In" redirects back to login page repeatedly.

Cause: OAuth configuration mismatch or Cloudflare Access misconfigured.

Solution:

  1. Verify GitHub OAuth callback URL matches:
    bash
    terraform output github_callback_url
  2. Check callback URL in GitHub OAuth app settings
  3. Verify CF_ACCESS_AUD matches Access application:
    bash
    terraform output cf_access_aud
  4. Check Cloudflare Access policies allow your email/domain

403 Forbidden After Login ​

Error: Authenticated but can't access the app.

Cause: Cloudflare Access policy too restrictive.

Solution:

  1. Go to Zero Trust → Access → Applications
  2. Find your Pixelflare application
  3. Edit policy to allow your email or GitHub organization
  4. Save and wait 1-2 minutes for propagation

Images Not Loading ​

Error: Upload works but images don't display (404 or broken images).

Cause: R2 bucket access issues or CDN routing problems.

Solution:

  1. Check image exists in R2:
  2. Check worker logs for errors:
    bash
    wrangler tail --config packages/api/wrangler.production.toml
  3. Verify DNS records are correct:
    • api.yourdomain.com → Worker route
    • cdn.yourdomain.com → Worker route (or R2 custom domain)

Upload Fails with "Invalid Upload Token" ​

Error: 401 Unauthorized when uploading images.

Cause: UPLOAD_TOKEN_SECRET missing or mismatched.

Solution:

bash
# Generate new secret
openssl rand -hex 32 | wrangler secret put UPLOAD_TOKEN_SECRET --config packages/api/wrangler.production.toml

# Or use existing from .env
echo "$UPLOAD_TOKEN_SECRET" | wrangler secret put UPLOAD_TOKEN_SECRET --config packages/api/wrangler.production.toml

File Too Large Error ​

Error: 413 Payload Too Large or "File is too large".

Cause: File exceeds 100MB upload limit.

Solution:

  • Compress image before upload
  • Maximum file size is 100MB (Cloudflare Workers limit)
  • For larger files, consider resizing or using a different format

Rate Limit Exceeded ​

Error: 429 Too Many Requests.

Cause: Hit rate limit for uploads or API calls.

Solution:

  • Wait 60 seconds and try again
  • Upload rate limits reset per minute
  • For production use, consider adjusting limits in code or enabling Stripe billing

Database Connection Errors ​

Error: 500 errors with "D1 binding not found" in logs.

Cause: D1 database binding not configured in wrangler.toml.

Solution:

bash
# Regenerate wrangler config
./scripts/tasks/05-generate-wrangler-config.cjs production

# Verify binding exists
cat packages/api/wrangler.production.toml | grep -A 3 "d1_databases"

AI Features Not Working ​

Error: "AI analysis is not enabled for this instance".

Cause: ENABLE_AI_CLASSIFICATION disabled or AI binding missing.

Solution:

  1. Set ENABLE_AI_CLASSIFICATION=true in .env
  2. Redeploy: make deploy
  3. Verify AI binding in wrangler.toml:
    bash
    cat packages/api/wrangler.production.toml | grep -A 2 "ai ="

Custom Domains Not Working ​

Error: "Custom domains feature not enabled".

Cause: Feature flag disabled or Cloudflare zone configuration missing.

Solution:

  1. Set ENABLE_CUSTOM_DOMAINS=true in .env
  2. Set CLOUDFLARE_ZONE_ID in .env
  3. Redeploy workers
  4. Custom domains require SSL/TLS Full mode in Cloudflare

Queue Processing Stuck ​

Error: Images uploaded but variants never generated.

Cause: Queue consumer not running or queue binding missing.

Solution:

  1. Check queue exists:
  2. Verify queue binding in wrangler.toml
  3. Check worker logs for queue consumer errors:
    bash
    wrangler tail --config packages/api/wrangler.production.toml
  4. Queues require Workers Paid plan ($5/month)

Configuration Issues ​

CORS Errors in Browser ​

Error: "blocked by CORS policy" in browser console.

Cause: API_HOST or APP_HOST environment variables incorrect.

Solution:

  1. Verify API_HOST matches your API worker URL
  2. Verify APP_HOST matches your frontend URL
  3. Check FRONTEND_HOST is set correctly
  4. Redeploy workers after fixing

TypeScript Build Errors ​

Error: Build fails with type errors.

Cause: Dependencies out of sync or breaking changes.

Solution:

bash
# Clean install
pnpm install

# Run type check
pnpm type-check

# Build packages in order
pnpm --filter @pixflare/shared --filter @pixflare/config build
pnpm build

Environment Variable Not Taking Effect ​

Error: Changed .env but app still uses old value.

Cause: Terraform variables not regenerated or worker not redeployed.

Solution:

bash
# Regenerate Terraform variables
./scripts/tasks/02-env-to-tfvars.cjs

# Apply Terraform changes
cd terraform && terraform apply

# Regenerate wrangler config
./scripts/tasks/05-generate-wrangler-config.cjs production

# Redeploy workers
make deploy-workers

Performance Issues ​

Slow Image Loading ​

Cause: No caching or variants not being used.

Solution:

  1. Enable Cloudflare cache on your zone
  2. Use variant URLs instead of original: /cdn/user/album/image.jpg?w=800
  3. Check KV cache is enabled (should be automatic)

High R2 Costs ​

Cause: Lots of Class A operations (PUT/DELETE) or egress.

Solution:

  • Enable variant generation to reduce original image fetches
  • Use Cloudflare cache to reduce R2 reads
  • Consider enabling R2 custom domain for built-in image resizing

Getting Help ​

Still stuck?

  1. Check GitHub Discussions for similar issues
  2. Review deployment logs for specific error messages
  3. Search existing issues
  4. Open a new issue with:
    • Error message (full text)
    • Steps to reproduce
    • Your environment (OS, Node version, etc.)
    • Relevant logs (redact secrets!)