Troubleshooting

Common problems and solutions for running Rabbithole.

Contents

  1. Clearing the page cache
  2. Pages look inconsistent across the site
  3. Broken links / 404s
  4. LLM refuses to generate a page
  5. Slow page generation
  6. API key errors
  7. Server won't start
  8. Debug logging

1. Clearing the Page Cache

ProblemA cached page has wrong content, broken layout, or you want to force the LLM to regenerate it.
CauseRabbithole permanently caches every generated page after its first request. Subsequent requests for the same URL are served directly from the cache without calling the LLM.
Solution Delete the cached file for the specific URL from the cache directory (default: ./cache/) and then reload the page in your browser.

The cache stores pages as files whose names are derived from the URL path. To clear a single page:

# Example: clear /about.html
rm cache/about.html

# Or clear ALL cached pages at once (use with caution)
rm -rf cache/*

After deletion, the next HTTP request for that URL will trigger a fresh LLM generation. The result will be cached again immediately.

Note: There is no built-in admin endpoint for cache invalidation. Cache clearing is currently a manual file-system operation. See the Architecture page for details on the cache layout.
Warning: Clearing the entire cache on a large site will cause a surge of LLM requests on the next visit to each URL. Consider clearing pages individually, or throttle traffic while the cache warms up.

2. Pages Look Inconsistent Across the Site

ProblemDifferent pages have different fonts, colors, navigation bars, or layouts — the site feels like a patchwork of unrelated designs.
CauseEach page is generated in complete isolation. A new LLM call receives only the prompt that was stored in the URL mapping. If that prompt does not describe the desired style, the LLM will invent its own.
Solution Include the full design specification in every prompt you write. Do not assume the next page's generator has seen any other page.

A well-specified prompt should include:

Example of a complete style block to paste into every prompt:

DESIGN: White background (#ffffff), black text (#000000), Arial/Helvetica/sans-serif
14px. Links #0000cc, visited #551a8b. No JS, no gradients, no external CSS.
Code/pre: #f4f4f4 bg, 1px solid #ccc, Courier New 13px.
H2 with 1px solid #cccccc bottom border. Max-width 860px centered.
NAV (pipe-separated, 13px): Home (/) | Getting Started (/getting-started.html) | ...
Tip: Think of each prompt as a complete creative brief for a designer who has never seen the rest of the site. The more context you encode, the more cohesive the result.
ProblemClicking a link on a generated page returns a 404, or leads to a page that has nothing to do with the expected content.
CauseThe LLM invented a URL in the HTML that was not included in the ---MAPPINGS--- output, or the JSON mapping was malformed and the server discarded it.
Solution Inspect the ---MAPPINGS--- output from the generation of the parent page and verify every <a href="..."> has a corresponding entry.

Diagnosing the problem

  1. Enable debug logging (see section 8) and look for lines about mapping parsing.
  2. Clear the parent page's cache so it is regenerated with a fresh mappings output.
  3. Check that the ---MAPPINGS--- line appears immediately after </html> with no intervening blank lines or text.
  4. Validate the JSON array with a linter — a trailing comma or unescaped character will cause the entire mappings block to be silently dropped.

Preventing the problem