Skip to content

Troubleshooting

Jump to bottom
Temp edited this page Feb 11, 2026 · 5 revisions

Troubleshooting

Common issues and their solutions when deploying and using R2-Manager-Worker.

Authentication Issues

❌ "Failed to authenticate" error

Symptoms:

  • Cannot access the application
  • Redirected to login repeatedly
  • 401 Unauthorized errors in console

Solutions:

  1. Verify TEAM_DOMAIN includes full URL:

    npx wrangler secret put TEAM_DOMAIN
# Enter: https://yourteam.cloudflareaccess.com

  2. Confirm POLICY_AUD matches Application Audience Tag:

    • Go to Zero Trust → Access → Applications → Select your app
    • Copy Application Audience (AUD) Tag from Overview tab
    • Set secret: npx wrangler secret put POLICY_AUD

  3. Check GitHub account is allowed:

    • Go to Zero Trust → Access → Applications → Select your app
    • Review Policies tab
    • Ensure your GitHub account matches the Allow policy

  4. Clear browser cookies:

    • Open DevTools (F12) → Application tab → Cookies
    • Delete all cookies for your domain
    • Try logging in again

  5. Verify JWT cookie is set:

    • After logging in, check DevTools → Application → Cookies
    • Look for cf-access-jwt-assertion cookie
    • If missing, check Cloudflare Access configuration

Bucket Issues

❌ "Bucket not found" error

Symptoms:

  • Cannot list files in bucket
  • Error message: "Failed to list files"
  • 404 errors in Worker logs

Solutions:

  1. Verify bucket exists:

    npx wrangler r2 bucket list

  2. Check bucket name in wrangler.toml:

    [[r2_buckets]]
binding = "BUCKET"
bucket_name = "exact-bucket-name"  # Must match exactly (case-sensitive)

  3. Verify ACCOUNT_ID is correct:

    • Go to Cloudflare Dashboard
    • Find Account ID in right sidebar
    • Update secret: npx wrangler secret put ACCOUNT_ID

  4. Check API token permissions:

    • Go to API Tokens page
    • Verify token has Workers R2 Storage → Edit permission
    • If missing, create new token with correct permissions
    • Update secret: npx wrangler secret put API_KEY

❌ Cannot create bucket

Symptoms:

  • "Failed to create bucket" error
  • Error about invalid bucket name

Solutions:

  1. Verify bucket name meets requirements:

    • Only lowercase letters (a-z), numbers (0-9), and hyphens (-)
    • Cannot begin or end with a hyphen
    • Must be 3-63 characters in length
    • Examples:
      • ✅ my-bucket-123
      • ✅ data-storage
      • ❌ My-Bucket (uppercase)
      • ❌ -invalid (starts with hyphen)
      • ❌ ab (too short)

  2. Check if bucket name already exists:

    npx wrangler r2 bucket list

Deployment Issues

❌ Worker deployment fails

Symptoms:

  • wrangler deploy command fails
  • Authentication errors during deploy
  • Build errors

Solutions:

  1. Re-authenticate with Cloudflare:

    npx wrangler login

  2. Verify secrets are set:

    npx wrangler secret list

    Should show:

    • ACCOUNT_ID
    • CF_EMAIL
    • API_KEY
    • TEAM_DOMAIN
    • POLICY_AUD

  3. Check build succeeds:

    npm run build

    If build fails, fix any TypeScript or linting errors.

  4. Verify wrangler.toml syntax:

    • Check for typos in configuration
    • Ensure multiline arrays use proper TOML syntax
    • Validate binding names match environment

  5. Check API token permissions: Token needs:

    • Account → Workers Scripts → Edit
    • Account → Workers R2 Storage → Edit
    • Zone → Workers Routes → Edit (if using custom domain)

❌ Assets not loading after deployment

Symptoms:

  • Blank page after deployment
  • 404 errors for JavaScript/CSS files
  • "Failed to fetch" errors in console

Solutions:

  1. Verify build was successful:

    npm run build

    Check that dist/ folder contains:

    • index.html
    • assets/ folder with JS and CSS files
    • Favicon and image files

  2. Check ASSETS binding in wrangler.toml:

    # Should be present (automatically configured by Wrangler)
# No manual configuration needed for assets

  3. Redeploy with fresh build:

    rm -rf dist
npm run build
npx wrangler deploy

CORS Errors

❌ CORS errors in browser console

Symptoms:

  • "CORS policy" error messages
  • API requests blocked by browser
  • Preflight OPTIONS requests failing

Solutions:

  1. Verify Cloudflare Access domain matches Worker domain:

    • Access application domain should match deployed Worker domain
    • Both should use same subdomain/domain

  2. Create Bypass policy for static assets:

    • Go to Zero Trust → Access → Applications → Select your app
    • Add Bypass policy for:
      • /site.webmanifest
      • /favicon.ico
      • /logo.png
      • Other static assets

  3. Check API requests include credentials:

    In src/services/api.ts:

    const response = await fetch(url, {
  ...options,
  credentials: "include", // Must be present
});

  4. Verify Worker CORS headers:

    Headers should include:

    'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS, PATCH',
'Access-Control-Allow-Headers': 'Content-Type, Authorization, ...'

Upload Issues

❌ Upload fails with large files (>100MB)

Symptoms:

  • Upload progress bar reaches 100% but fails
  • "Upload failed" error
  • Worker returns 413 or 500 error

Solutions:

  1. Check your Cloudflare plan limits:

    • Free/Pro Plans: 100MB maximum
    • Business Plan: 200MB maximum
    • Enterprise Plan: 500MB maximum

  2. Upgrade plan if needed:

    • Go to Cloudflare Dashboard
    • Navigate to Plans section
    • Upgrade to Business or Enterprise for larger uploads

  3. Use chunked uploads:

    • Application automatically chunks files >10MB
    • Ensure chunking logic in src/services/api.ts is working
    • Check Worker receives correct chunk headers

  4. Verify Worker can handle chunk assembly:

    • Check Worker logs for chunk processing
    • Ensure all chunks are received before final upload

❌ Upload succeeds but file not visible

Symptoms:

  • Upload completes successfully
  • File not shown in file list
  • Need to refresh page to see file

Solutions:

  1. Force cache refresh:

    • Click refresh icon in UI
    • Or add ?skipCache=true to list request

  2. Check file isn't filtered:

    • Worker filters out assets/ folder
    • Ensure file name doesn't match filter criteria

  3. Verify file list pagination:

    • File might be on a different page
    • Check pagination cursor is correct

Performance Issues

❌ Slow bucket operations

Symptoms:

  • Bucket rename takes very long
  • Force delete hangs
  • Timeout errors

Solutions:

  1. For large buckets, be patient:

    • Bucket operations iterate through all objects
    • Rate limiting delays are built-in (500ms between batches)
    • 1000 objects ≈ 5-10 minutes

  2. Check Worker logs:

    npx wrangler tail

    Look for progress messages showing object processing

  3. For stuck operations:

    • Check if Worker is still running
    • View logs in dashboard: Workers & Pages → Select Worker → Logs
    • May need to wait for timeout and retry

Local Development Issues

❌ "Port already in use"

Symptoms:

  • Cannot start Vite dev server
  • Cannot start Wrangler dev
  • EADDRINUSE error

Solutions:

  1. Kill processes using ports:

    npx kill-port 5173  # Vite
npx kill-port 8787  # Wrangler

  2. Or manually find and kill:

    # On macOS/Linux
lsof -ti:5173 | xargs kill -9
lsof -ti:8787 | xargs kill -9

# On Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

❌ Module not found errors

Symptoms:

  • Import errors in console
  • TypeScript errors about missing modules
  • Build fails with module errors

Solutions:

  1. Clear and reinstall node_modules:

    rm -rf node_modules package-lock.json
npm install

  2. Clear Vite cache:

    rm -rf node_modules/.vite
npm run dev

  3. Verify Node.js version:

    node --version  # Should be 18+

❌ Authentication doesn't work locally

This is expected behavior!

  • JWT validation is disabled on localhost
  • All API endpoints are accessible without tokens
  • This is intentional for easier development

To test with authentication:

  1. Deploy to production and test there, OR
  2. Set .env to use deployed Worker URL: 
    VITE_WORKER_API=https://your-worker.workers.dev

JWT Token Issues

❌ Token validation fails

Symptoms:

  • 401 errors despite being logged in
  • "JWT validation failed" in Worker logs
  • Token appears in cookies but still unauthorized

Solutions:

  1. Verify token in jwt.io:

    • Copy cf-access-jwt-assertion cookie value from DevTools
    • Paste into jwt.io
    • Check:
      • iss matches your team domain
      • aud contains your Application Audience Tag
      • exp hasn't passed (token not expired)

  2. Check TEAM_DOMAIN format:

    # Must include https:// and full domain
npx wrangler secret put TEAM_DOMAIN
# Enter: https://yourteam.cloudflareaccess.com

  3. Verify POLICY_AUD:

    npx wrangler secret put POLICY_AUD
# Enter: Application Audience Tag from Access dashboard

  4. Enable debug logging:

    Add to worker/index.ts:

    console.log("[JWT Debug]", {
  tokenPresent: !!token,
  issuer: env.TEAM_DOMAIN,
  audience: env.POLICY_AUD,
  payload: payload,
});

    View logs: npx wrangler tail

Custom Domain Issues

❌ Custom domain not working

Symptoms:

  • 404 when accessing custom domain
  • DNS resolution fails
  • SSL certificate errors

Solutions:

  1. Verify domain is on Cloudflare:

    • Domain must be managed by Cloudflare
    • DNS must be proxied (orange cloud)

  2. Check route configuration in wrangler.toml:

    [[routes]]
pattern = "r2.yourdomain.com"
custom_domain = true

  3. Verify DNS records:

    • Go to Cloudflare Dashboard → DNS
    • Should see CNAME or A record for subdomain
    • Must be proxied (orange cloud icon)

  4. Wait for DNS propagation:

    • Can take 5-30 minutes for DNS changes
    • Use dig or nslookup to check: 
      dig r2.yourdomain.com

  5. Check SSL certificate:

    • Cloudflare automatically provisions certificates
    • May take a few minutes after DNS propagation
    • Check in dashboard: SSL/TLS → Edge Certificates

Browser-Specific Issues

❌ Safari issues with cookies

Symptoms:

  • Authentication works in Chrome but not Safari
  • Cookies not being set in Safari

Solutions:

  1. Disable "Prevent cross-site tracking":

    • Safari → Preferences → Privacy
    • Uncheck "Prevent cross-site tracking"

  2. Or use Cloudflare Access for Safari:

    • This is a Safari privacy feature
    • Cloudflare Access should handle this automatically
    • If issues persist, check Access configuration

Rate Limiting Issues

❌ "Rate limit exceeded" (429 error)

Symptoms:

  • API requests return 429 status code
  • Error message: "Rate limit exceeded"
  • Operations fail with "Please wait before retrying"

Solutions:

  1. Wait before retrying:

    • Check the Retry-After header in the response
    • Wait the specified duration (typically 60 seconds) before making more requests
    • Rate limits reset automatically after the time period

  2. Reduce request frequency:

    • Implement client-side caching for frequently accessed data
    • Use bulk operations where available
    • Batch multiple operations into fewer API calls

  3. Check which tier is rate limiting:

    • Review the X-RateLimit-Tier header in the response
    • READ tier: 100 requests per 60 seconds
    • WRITE tier: 30 requests per 60 seconds
    • DELETE tier: 10 requests per 60 seconds

  4. Implement exponential backoff:

    async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const retryAfter = error.headers.get("Retry-After") || 60;
        await new Promise((resolve) =>
          setTimeout(resolve, retryAfter * 1000),
        );
      } else {
        throw error;
      }
    }
  }
}

  5. Check Worker logs for violations:

    npx wrangler tail

    Look for [Rate Limit] entries showing which operations are being rate limited

❌ Rate limiting not working in production

Symptoms:

  • Rate limits not being enforced
  • No 429 responses when expecting them
  • Rate limit violations not logged

Solutions:

  1. Verify rate limiting bindings in wrangler.toml:

    [[ratelimits]]
name = "RATE_LIMITER_READ"
namespace_id = "1001"
simple = { limit = 100, period = 60 }

[[ratelimits]]
name = "RATE_LIMITER_WRITE"
namespace_id = "1002"
simple = { limit = 30, period = 60 }

[[ratelimits]]
name = "RATE_LIMITER_DELETE"
namespace_id = "1003"
simple = { limit = 10, period = 60 }

  2. Check Wrangler version:

    npx wrangler --version

    Rate limiting requires Wrangler 4.36.0 or later. Update if necessary:

    npm install -D wrangler@latest

  3. Verify deployment succeeded:

    npx wrangler deployments list

    Ensure the latest deployment includes rate limiting configuration

  4. Check if you're testing from localhost:

    • Rate limiting is automatically disabled for localhost requests
    • Test from your deployed production URL instead

  5. Verify Cloudflare Workers plan:

    • Rate limiting requires a paid Cloudflare Workers plan ($5/month minimum)
    • Check your plan at Cloudflare Dashboard
    • To upgrade: Dashboard → Workers & Pages → Manage Subscription → Select Paid Plan
    • Note: All other features work on the free tier

❌ Different rate limits needed for different users

Symptoms:

  • Want higher limits for admin users
  • Need per-user or per-role rate limits
  • Current tiered limits are too restrictive/permissive

Solutions:

  1. Current implementation uses per-user limits:

    • All authenticated users have the same rate limits
    • Limits are enforced independently per user (by email)
    • One user hitting limits doesn't affect others

  2. To implement custom per-user limits (requires code modification):

    Edit worker/utils/ratelimit.ts:

    // Define user tiers
const ADMIN_USERS = ["admin@example.com"];
const POWER_USERS = ["power@example.com"];

function getRateLimiter(env: Env, tier: RateLimitTier, userEmail: string) {
  // Give admins higher limits
  if (ADMIN_USERS.includes(userEmail)) {
    switch (tier) {
      case "READ":
        return { limiter: env.RATE_LIMITER_READ, limit: 500, period: 60 };
      case "WRITE":
        return { limiter: env.RATE_LIMITER_WRITE, limit: 150, period: 60 };
      case "DELETE":
        return { limiter: env.RATE_LIMITER_DELETE, limit: 50, period: 60 };
    }
  }

  // Use default limits
  return getRateLimiter(env, tier);
}

  3. To adjust global rate limits:

    Edit limits in wrangler.toml:

    [[ratelimits]]
name = "RATE_LIMITER_READ"
namespace_id = "1001"
simple = { limit = 200, period = 60 }  # Increased from 100

    Then redeploy:

    npx wrangler deploy

❌ Rate limit violations being logged excessively

Symptoms:

  • Worker logs filled with rate limit violations
  • Too many [Rate Limit] entries
  • Difficult to find other log messages

Solutions:

  1. This is expected behavior:

    • All rate limit violations are logged for security monitoring
    • Helps identify potential abuse or misconfigured clients

  2. To reduce violations:

    • Implement proper retry logic in your API client
    • Add client-side request throttling
    • Use caching to reduce redundant API calls

  3. To filter logs:

    # View only non-rate-limit logs
npx wrangler tail | grep -v "Rate Limit"

# View only rate limit violations
npx wrangler tail | grep "Rate Limit"

  4. To disable violation logging (not recommended):

    Edit worker/utils/ratelimit.ts and comment out the logging:

    if (!success) {
  // console.warn('[Rate Limit] Limit exceeded', { ... });
}

Getting Help

If you're still experiencing issues:

  1. Check Worker logs:

    npx wrangler tail

  2. Enable debug mode:

    • Add verbose logging to Worker
    • Check browser console for errors
    • Review Network tab in DevTools

  3. Search GitHub Issues:

  4. Open a new issue:

    • Visit GitHub Issues
    • Include:
      • Clear description of the problem
      • Steps to reproduce
      • Error messages and logs
      • Browser and OS information
      • Screenshots if relevant

  5. Ask in Discussions:

Additional Resources

R2 Bucket Manager Wiki

Getting Started

Core Features

Development

Security & Authentication

Support & Resources

External Links

Clone this wiki locally