Replit Debug Bundle Skill

Replit Debug Bundle

Current State

!node --version 2>/dev/null || echo 'Node: N/A' !python3 --version 2>/dev/null || echo 'Python: N/A' !echo "REPL_SLUG=$REPL_SLUG REPL_OWNER=$REPL_OWNER" 2>/dev/null || echo 'Not on Replit'

Overview

Collect all diagnostic information needed to debug Replit workspace, deployment, and database issues. Produces a redacted evidence bundle safe for sharing with Replit support.

Prerequisites

Shell access in Replit Workspace
Permission to read logs and configuration
Access to deployment monitoring (if deployed)

Instructions

Step 1: Automated Debug Bundle Script

#!/bin/bash
set -euo pipefail
# replit-debug-bundle.sh

BUNDLE="replit-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"/{env,db,config,network,packages}

echo "=== Replit Debug Bundle ===" > "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "" >> "$BUNDLE/summary.txt"

# 1. Environment info
echo "--- Runtime ---" >> "$BUNDLE/env/runtime.txt"
node --version >> "$BUNDLE/env/runtime.txt" 2>&1 || echo "Node: N/A" >> "$BUNDLE/env/runtime.txt"
python3 --version >> "$BUNDLE/env/runtime.txt" 2>&1 || echo "Python: N/A" >> "$BUNDLE/env/runtime.txt"
uname -a >> "$BUNDLE/env/runtime.txt"

# 2. Replit environment variables (safe ones only)
echo "--- Replit Env ---" >> "$BUNDLE/env/replit-vars.txt"
echo "REPL_SLUG=$REPL_SLUG" >> "$BUNDLE/env/replit-vars.txt"
echo "REPL_OWNER=$REPL_OWNER" >> "$BUNDLE/env/replit-vars.txt"
echo "REPL_ID=$REPL_ID" >> "$BUNDLE/env/replit-vars.txt"
echo "REPLIT_DB_URL=${REPLIT_DB_URL:+SET}" >> "$BUNDLE/env/replit-vars.txt"
echo "DATABASE_URL=${DATABASE_URL:+SET}" >> "$BUNDLE/env/replit-vars.txt"
echo "NODE_ENV=${NODE_ENV:-unset}" >> "$BUNDLE/env/replit-vars.txt"

# 3. Package versions
npm list --depth=0 > "$BUNDLE/packages/npm.txt" 2>&1 || true
pip list > "$BUNDLE/packages/pip.txt" 2>&1 || true

# 4. Configuration files (redacted)
cp .replit "$BUNDLE/config/.replit" 2>/dev/null || echo "No .replit" > "$BUNDLE/config/.replit"
cp replit.nix "$BUNDLE/config/replit.nix" 2>/dev/null || echo "No replit.nix" > "$BUNDLE/config/replit.nix"

# 5. Database connectivity
echo "--- Database ---" >> "$BUNDLE/db/status.txt"
if [ -n "${DATABASE_URL:-}" ]; then
  echo "PostgreSQL: configured" >> "$BUNDLE/db/status.txt"
  # Test connection without exposing credentials
  node -e "const {Pool}=require('pg');const p=new Pool({connectionString:process.env.DATABASE_URL,ssl:{rejectUnauthorized:false}});p.query('SELECT 1').then(()=>console.log('Connected')).catch(e=>console.log('Failed:',e.message)).finally(()=>p.end())" >> "$BUNDLE/db/status.txt" 2>&1 || echo "pg not installed" >> "$BUNDLE/db/status.txt"
fi
if [ -n "${REPLIT_DB_URL:-}" ]; then
  echo "Replit KV DB: configured" >> "$BUNDLE/db/status.txt"
  curl -s "$REPLIT_DB_URL?prefix=" | head -20 >> "$BUNDLE/db/kv-keys.txt" 2>/dev/null || echo "KV DB unreachable" >> "$BUNDLE/db/status.txt"
fi

# 6. Network connectivity
echo "--- Network ---" >> "$BUNDLE/network/connectivity.txt"
curl -s -o /dev/null -w "replit.com: HTTP %{http_code} (%{time_total}s)\n" https://replit.com >> "$BUNDLE/network/connectivity.txt"
curl -s -o /dev/null -w "status.replit.com: HTTP %{http_code} (%{time_total}s)\n" https://status.replit.com >> "$BUNDLE/network/connectivity.txt"

# 7. Disk usage
df -h / > "$BUNDLE/env/disk.txt" 2>/dev/null
du -sh . >> "$BUNDLE/env/disk.txt" 2>/dev/null

# 8. Process state
ps aux | head -20 > "$BUNDLE/env/processes.txt" 2>/dev/null

# Package bundle
tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
echo ""
echo "Debug bundle created: $BUNDLE.tar.gz"
echo "Size: $(du -h "$BUNDLE.tar.gz" | cut -f1)"
rm -rf "$BUNDLE"

Step 2: Quick Health Check

set -euo pipefail
# Fast triage without full bundle
echo "=== Quick Replit Health Check ==="
echo "Repl: $REPL_SLUG (owner: $REPL_OWNER)"
echo "Node: $(node --version 2>/dev/null || echo N/A)"
echo "Python: $(python3 --version 2>/dev/null || echo N/A)"
echo "DB URL: ${DATABASE_URL:+configured}"
echo "KV URL: ${REPLIT_DB_URL:+configured}"
echo "Disk: $(df -h / | tail -1 | awk '{print $3 "/" $2 " (" $5 " used)"}')"
curl -s -o /dev/null -w "Replit.com: %{http_code}\n" https://replit.com
curl -s https://status.replit.com/api/v2/summary.json 2>/dev/null | \
  python3 -c "import sys,json;d=json.load(sys.stdin);print('Status:', d['status']['description'])" 2>/dev/null || echo "Status: check https://status.replit.com"

Step 3: Deployment-Specific Diagnostics

set -euo pipefail
# Check deployment health
DEPLOY_URL="https://your-app.replit.app"  # Replace with your URL

echo "=== Deployment Diagnostics ==="
curl -s -o /dev/null -w "Status: %{http_code}, Time: %{time_total}s\n" "$DEPLOY_URL/health"

# Check response headers
curl -sI "$DEPLOY_URL" | grep -iE "^(server|x-replit|content-type|cache)"

# Measure cold start (if autoscale)
echo "Cold start test (wait 5 min for sleep, then):"
echo "time curl -s $DEPLOY_URL/health"

Sensitive Data Handling

ALWAYS REDACT before sharing:

API keys, tokens, passwords
DATABASE_URL connection strings
PII (emails, names, IDs)
REPL_IDENTITY tokens

Safe to include:

Error messages and stack traces
Package versions
.replit and replit.nix contents
HTTP status codes and response times

Error Handling

| Item | Purpose | Safe to Share | |------|---------|---------------| | Runtime versions | Compatibility check | Yes | | Replit env vars (names only) | Configuration status | Yes | | Package list | Dependency conflicts | Yes | | Network latency | Connectivity issues | Yes | | Disk usage | Storage problems | Yes | | Connection strings | Database access | NEVER |

Submit to Support

Create bundle: bash replit-debug-bundle.sh
Review for sensitive data
Open support ticket at https://replit.com/support
Attach the .tar.gz bundle
Include: steps to reproduce, expected vs actual behavior

Resources

Next Steps

For rate limit issues, see replit-rate-limits.

Agent Skills: Replit Debug Bundle

Install this agent skill to your local

Skill Files