Glitch Diagnostic Guide: Fix Sleep, Build, Port, Env, and Rate Limit Issues

Recognizable Conditions and Quick Fixes

• Project appears asleep: No logs, preview unresponsive after inactivity.
• Build failures: npm ERR! code ERESOLVE or missing dependencies.
• Port binding error: EADDRINUSE on port 3000.
• Environment variables undefined: .env not loaded or variables missing at runtime.
• API throttling: 429 Too Many Requests from external services.

Diagnosis Table: Symptom to Root Cause

Condition	Most Likely Cause	Key Check
No logs, preview dead	Automatic sleep mode	View status badge or ping URL
npm install fails	Node version mismatch	Run node -v in terminal
EADDRINUSE error	Port already bound	Run lsof -i :3000
.env vars undefined	dotenv not loaded	Check for require('dotenv')
429 rate limit	Shared IP throttling	Review Retry-After headers

Step-by-Step Diagnostic Checks and Fixes

1. Project Sleep Mode (Free Tier Only)

Glitch free projects automatically sleep after 5 minutes of inactivity. This causes delays on first access and stops background processes.

Check: Look for the project status badge in the editor. A gray badge indicates sleep state.

Fix: Interact with the project—edit any file or send a request to the preview URL. For production apps, upgrade to a paid plan to disable sleep entirely.

Escalation: If the project remains unresponsive after 2 minutes of interaction, note the project ID and contact Glitch support.

2. Build Failures with ERESOLVE

ESRESOLVE errors occur when package.json specifies versions incompatible with Glitch's default Node.js version (currently Node 16).

Check: Run glitch logs in the terminal to see the full install error. Then run node -v to confirm the Node version.

Fix: Either:

1. Downgrade packages in package.json to versions compatible with Node 16.
2. Add an engines field to package.json:

"engines": {
  "node": ">=18"
}

Escalation: If manual npm install still fails, delete the node_modules folder and lockfile, then reinstall.

3. Port Binding Error EADDRINUSE

The error Error: listen EADDRINUSE: address already in use :::3000 means another process is using the expected port.

Check: In terminal, run:

lsof -i :3000
ps aux | grep node
Fix: Kill the conflicting process with kill -9 <pid>, or modify your server code to use:
process.env.PORT || 3000
Escalation: If the port remains occupied, restart the container via the project settings. Persistent issues require a support ticket.

4. Environment Variables Not Loading
Glitch does not automatically load .env files. Variables must be explicitly loaded or set via the UI.
Check: Verify the .env file exists and contains the expected variables. Confirm your entry file includes:
require('dotenv').config()
Fix: Add the dotenv require at the top of your main file, or use Glitch's Environment Variables UI under Project Settings > Environment Variables.
Escalation: If variables still appear undefined, ensure the project is not in sleep mode and consider upgrading to a paid plan for more reliable state.

5. API Rate Limiting (429 Errors)
Free Glitch projects share outbound IP addresses. External APIs may enforce rate limits per IP, causing 429 errors.
Check: Inspect response headers for Retry-After or X-RateLimit-Reset. Review logs for request frequency.
Fix: Implement exponential backoff in your fetch calls, cache responses where possible, and consolidate redundant requests.
Escalation: If throttling continues, contact the API provider with your IP range. Paid Glitch plans offer dedicated IPs.

Verification Steps After Applying Fixes

Refresh the project preview and confirm the server responds correctly.
Run the relevant diagnostic command (e.g., lsof, npm install, env check) and verify output shows resolution.
Monitor the project for at least 5 minutes of inactivity to ensure sleep-related issues do not recur.


Important Cautions

Never commit secrets: Use Glitch's Environment Variables UI instead of storing keys in code or .env files committed to the editor.
Avoid large files: Files over 100 MB can cause build failures since Glitch enforces a 200 MB project storage limit.


When to Seek Help from Glitch Support

Project remains asleep after active interaction for more than 2 minutes.
Build failures persist after aligning Node versions and clearing node_modules.
Port conflicts continue after killing processes and restarting the container.
Environment variables are missing despite correct configuration and active project state.
Rate limiting from external APIs cannot be resolved with backoff or caching.