If you're running a Claude Code site on Linux, debugging is less about guessing and more about narrowing the blast radius. Most failures fall into a few buckets: the app didn't start, the web server can't reach it, the domain points somewhere else, or a recent change introduced a regression. This guide shows you how to troubleshoot a Claude Code site on Linux with a process that works whether you're on a fresh project or maintaining something that has already shipped.
The goal is to avoid the classic trap of changing three things at once. If you use Claude Code inside a real Linux host, keep the debugging loop tight: reproduce, inspect logs, verify the service boundary, and only then edit code. That approach saves hours, especially on sites that include Flask, Node, Python workers, Nginx, or background jobs.
How to troubleshoot a Claude Code site on Linux without guessing
Start by classifying the problem. Not every broken site is a code bug. A fast triage session usually answers one question: where is the request failing?
1) Is the site down for everyone or just one path?
Before opening the codebase, test a few different URLs:
- Homepage — does the root path load?
- Health endpoint — if you have one, does it respond?
- Admin or login page — does the failure happen only on authenticated routes?
- Static assets — do CSS and images load correctly?
If the homepage works but a specific route fails, you're probably looking at an app-level issue. If everything fails with a 502, 504, or blank response, check the reverse proxy and process manager first.
2) Read the exact error message
It sounds obvious, but many debugging sessions stall because the error text is treated as background noise. A 500, 502, timeout, permission denied, and connection refused all mean different things.
Keep a short mapping in your head:
- 500 Internal Server Error — the app handled the request and crashed or raised an exception.
- 502 Bad Gateway — Nginx or another proxy could not talk to your app server.
- 503 Service Unavailable — the app is temporarily unavailable or deliberately refusing traffic.
- 504 Gateway Timeout — the upstream service took too long to respond.
- Connection refused — the port is wrong, the service is stopped, or the app never bound to the socket.
That one detail usually tells you which layer to inspect first.
Check the Linux service layer first
On a Linux host, a lot of “site issues” are really service issues. Your app may be healthy in code but dead as a process.
Use systemd or your process manager to confirm the app is running
If your app is managed by systemd, check status, recent failures, and restart loops. If you're using a custom process manager, look for the equivalent state.
- Is the process active?
- Did it restart repeatedly?
- Did it exit immediately after boot?
- Are there memory or file permission errors in the startup logs?
If the process won't stay up, don't touch the web server yet. Fix the boot failure first. Common causes include:
- missing environment variables
- broken dependency install
- syntax error in the entrypoint
- wrong Python/Node runtime version
- permission problems on the app directory or uploaded files
Look at the application logs, not just the proxy logs
Proxy logs tell you that a request failed. App logs tell you why. For a Claude Code site on Linux, the highest-value files are usually:
- application stdout/stderr logs
- framework logs, such as Flask, Django, or Express errors
- worker logs for background jobs
- deployment logs from the last restart or release
If your framework prints a traceback, read it from the top of the stack. The first error is often the real one. The last error may just be a symptom.
Check memory and disk pressure
Some bugs aren't bugs at all; they're resource problems. A site that works on a local machine can fail on a smaller host if it runs out of RAM, disk, or temporary space.
Watch for signs like:
- requests failing under load
- the app restarting after large uploads
- package installs failing mid-way
- logs showing out-of-memory kills
A good habit is to inspect free memory, disk usage, and inode consumption before assuming the code is broken. If uploads, caches, or backups have filled the disk, the app may fail in strange ways.
How to troubleshoot a Claude Code site on Linux by isolating layers
The cleanest debugging path is to isolate the stack from top to bottom. Think in layers:
- DNS — does the domain point to the right server?
- Nginx or reverse proxy — is it accepting traffic?
- App server — is the upstream process alive and listening?
- Framework code — is the route or template throwing?
- Data layer — is the database or cache responding?
When you test these layers one by one, you stop chasing phantom bugs.
DNS and domain checks
If the site works on the host's local address but not on the public domain, verify the domain first. Common mistakes include:
- an A record still pointing at an old server
- Cloudflare proxy settings hiding the real origin issue
- mixed www and apex records
- SSL certificate mismatch after a domain change
When I'm debugging a release, I like to confirm both the public URL and the local upstream URL. If one works and the other doesn't, the problem is probably not in the app.
Reverse proxy checks
Nginx can fail quietly if the upstream address is wrong or the app port changed. Look for:
- invalid upstream host or port
- bad SSL configuration
- access rules blocking a path
- rewrite rules sending requests to the wrong place
A useful test is to bypass the proxy temporarily and hit the app server directly from localhost. If that works, your app is fine and the problem sits in Nginx or the TLS layer.
App server and socket checks
Your app must actually listen on the port the proxy expects. This is where launch-time mismatches happen:
- the app started on 5000, but Nginx expects 8000
- the app bound to 127.0.0.1 while the proxy is reaching a container address
- the service file points to the wrong working directory
Check the binding address, port, and environment variables. Many “it worked yesterday” issues turn out to be a changed port or an overwritten config file.
Common failure patterns in Claude Code sites
Some classes of bugs show up again and again in AI-built Linux projects. Knowing them saves time.
Environment variables are missing or stale
Claude Code can generate clean app logic, but deployment often fails because the runtime config wasn't updated. If the app depends on database URLs, API keys, or feature flags, confirm the values exist in the actual server environment, not just in a .env file that never got loaded.
Best practice:
- document every required env var
- compare staging vs production values
- restart the app after changing secrets
- avoid copy-pasting stale files into live releases
Dependencies changed underneath you
Package updates can break a project that seemed stable. Python libraries, npm packages, and system packages all drift. If your site starts failing after a deploy, compare the lockfile and installed versions before rewriting code.
Look for:
- deprecated methods
- major version bumps
- native module build errors
- framework incompatibilities
File permissions block uploads or generated output
AI-built sites often generate files, cache assets, write uploads, or export reports. That means permissions matter. If a user action fails only when writing to disk, check ownership and write access on the target directory.
Symptoms include:
- upload endpoints returning 500
- cache files not being created
- CSV or PDF exports silently failing
- background jobs unable to write temp files
Database migrations are half-applied
A migration that ran locally may fail on production because the schema is older, the table is larger, or a lock is held. If the app starts but specific pages break, check for schema mismatches and partially applied migrations.
Useful signs:
- new columns missing in production
- ORM errors on one route only
- jobs failing after a deploy that changed the schema
A practical troubleshooting checklist for Claude Code on Linux
When a site is broken, this is the checklist I would run in order:
- Confirm the user-facing symptom. Note the exact URL, error code, and time.
- Check whether it's global or route-specific.
- Inspect the app service status. Look for crashes or restart loops.
- Read the app logs. Find the first real exception.
- Verify Nginx or proxy configuration. Confirm the upstream host and port.
- Test the app locally on the host. Bypass the proxy if needed.
- Check DNS and SSL. Make sure the domain and certificate match the origin.
- Review recent changes. Look at the last deploy, config edits, package changes, or migrations.
- Check system resources. Memory, disk, and CPU pressure can mimic code bugs.
- Fix one thing at a time. Re-test after every change.
That last step matters. If you change both the app and the server config, you won't know which fix actually worked.
How to work with Claude Code during debugging
Claude Code is most useful when you feed it a tight, factual problem statement. Instead of saying “my site is broken,” give it the evidence:
- the exact URL
- the status code or traceback
- relevant log lines
- recent code or config changes
- what you expected to happen
A better prompt is:
“The homepage returns 502 after yesterday's deploy. Nginx upstream points to 127.0.0.1:8000. The app service is running, but the app logs show a ModuleNotFoundError for psycopg2. Here are the last 30 log lines. What's the most likely failure, and what should I check next?”
That kind of prompt usually gets you to a fix faster than asking for generic advice. If you're running your project on Vibesies, this is exactly the kind of workflow the platform is meant for: a real Linux environment, a persistent agent, and enough control to investigate the actual failure rather than a simulated one.
When to stop debugging and roll back
Sometimes the fastest fix is to undo the last change. Roll back if:
- the failure started immediately after deploy
- the new release changed multiple subsystems
- you can't reproduce the bug locally
- the site is customer-facing and the issue is growing
Rollback is not failure. It's a stability move. Once the site is healthy, you can inspect the bad change in a calmer environment.
Conclusion: how to troubleshoot a Claude Code site on Linux the right way
If you remember only one thing from this guide, make it this: how to troubleshoot a Claude Code site on Linux comes down to isolating layers, reading logs carefully, and changing one variable at a time. Most incidents are fixable once you know whether the problem lives in DNS, Nginx, the app process, the framework, or the database.
For power users building on a real Linux host, that process is even more important than the code itself. A good debugging routine makes your site easier to maintain, easier to hand off, and less likely to break at 2 a.m. If you're hosting a persistent Claude Code project on Vibesies or a similar Linux environment, keep this checklist close and use it before you start rewriting code.
