Troubleshooting Guide

Common issues and solutions for AdBlock Compiler.

Table of Contents

• Installation Issues
• Compilation Errors
• Performance Issues
• Network & API Issues
• Cache Issues
• Deployment Issues
• Platform-Specific Issues

Installation Issues

Package not found on JSR

Error:

error: JSR package not found: @jk-com/adblock-compiler

Solution: Use npm import as fallback:

import { compile } from 'npm:@jk-com/adblock-compiler';

Or install via npm:

npm install @jk-com/adblock-compiler

Deno version incompatibility

Error:

error: Unsupported Deno version

Solution: AdBlock Compiler requires Deno 2.0 or higher:

deno upgrade
deno --version  # Should be 2.0.0 or higher

Permission denied errors

Error:

error: Requires net access to "example.com"

Solution: Grant necessary permissions:

# Allow all network access
deno run --allow-net your-script.ts

# Allow specific hosts
deno run --allow-net=example.com,github.com your-script.ts

# For file access
deno run --allow-read --allow-net your-script.ts

Compilation Errors

Invalid configuration

Error:

ValidationError: Invalid configuration: sources is required

Solution: Ensure your configuration has required fields:

const config: IConfiguration = {
    name: 'My Filter List', // REQUIRED
    sources: [ // REQUIRED
        {
            name: 'Source 1',
            source: 'https://example.com/list.txt',
        },
    ],
    // Optional fields...
};

Source fetch failures

Error:

Error fetching source: 404 Not Found

Solutions:

1. Check URL validity:

// Verify the URL is accessible
const response = await fetch(sourceUrl);
console.log(response.status); // Should be 200

2. Handle 404s gracefully:

// Use exclusions_sources to skip broken sources
const config = {
    name: 'My List',
    sources: [
        { name: 'Good', source: 'https://good.com/list.txt' },
        { name: 'Broken', source: 'https://broken.com/404.txt' },
    ],
    exclusions_sources: ['https://broken.com/404.txt'],
};

3. Check circuit breaker:

Source temporarily disabled due to repeated failures

Wait 5 minutes for circuit breaker to reset, or check the source availability.

Transformation errors

Error:

TransformationError: Invalid rule at line 42

Solution: Enable validation transformation to see detailed errors:

const config = {
  name: "My List",
  sources: [...],
  transformations: [
    "Validate",  // Add this to see validation details
    "RemoveComments",
    "Deduplicate"
  ]
};

Memory issues

Error:

JavaScript heap out of memory

Solutions:

1. Increase memory limit (Node.js):

node --max-old-space-size=4096 your-script.js

2. Use streaming for large files:

// Process sources in chunks
const config = {
    sources: smallBatch, // Process 10-20 sources at a time
    transformations: ['Compress', 'Deduplicate'],
};

3. Enable compression:

transformations: ['Compress']; // Reduces memory usage

Performance Issues

Slow compilation

Symptoms:

• Compilation takes >60 seconds
• High CPU usage
• Unresponsive UI

Solutions:

1. Enable caching (API/Worker):

// Cloudflare Worker automatically caches
// Check cache headers:
X-Cache-Status: HIT

2. Use batch API for multiple lists:

// Compile in parallel
POST /compile/batch
{
  "requests": [
    { "id": "list1", "configuration": {...} },
    { "id": "list2", "configuration": {...} }
  ]
}

3. Optimize transformations:

// Minimal transformations for speed
transformations: [
    'RemoveComments',
    'Deduplicate',
    'RemoveEmptyLines',
];

// Remove expensive transformations like:
// - Validate (checks every rule)
// - ConvertToAscii (processes every character)

4. Check source count:

// Limit to 20-30 sources max
// Too many sources = slow compilation
console.log(config.sources.length);

High memory usage

Solution:

// Use Compress transformation
transformations: ['Compress', 'Deduplicate'];

// This reduces memory usage by 70-80%

Request deduplication not working

Issue: Multiple identical requests all compile instead of using cached result.

Solution: Ensure requests are identical:

// These are DIFFERENT requests (different order)
const req1 = { sources: [a, b] };
const req2 = { sources: [b, a] };

// These are IDENTICAL (will be deduplicated)
const req1 = { sources: [a, b] };
const req2 = { sources: [a, b] };

Check for deduplication:

X-Request-Deduplication: HIT

Network & API Issues

Rate limiting

Error:

429 Too Many Requests
Retry-After: 60

Solution: Respect rate limits:

const retryAfter = response.headers.get('Retry-After');
await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));

Rate limits:

• Per IP: 60 requests/minute
• Per endpoint: 100 requests/minute

CORS errors

Error:

Access to fetch at 'https://...' from origin 'https://...' has been blocked by CORS

Solution: Use the API endpoint which has CORS enabled:

// ✅ CORRECT - CORS enabled
fetch('https://adblock-compiler.jayson-knight.workers.dev/compile', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ configuration }),
});

// ❌ WRONG - Direct source fetch (no CORS)
fetch('https://random-site.com/list.txt');

Timeout errors

Error:

TimeoutError: Request timed out after 30000ms

Solution:

1. Check source availability:

curl -I https://source-url.com/list.txt

2. Circuit breaker will retry:

• Automatic retry with exponential backoff
• Up to 3 attempts
• Then source is temporarily disabled

3. Use fallback sources:

sources: [
    { name: 'Primary', source: 'https://primary.com/list.txt' },
    { name: 'Mirror', source: 'https://mirror.com/list.txt' }, // Fallback
];

SSL/TLS errors

Error:

error: Invalid certificate

Solution:

# Deno - use --unsafely-ignore-certificate-errors (not recommended)
deno run --unsafely-ignore-certificate-errors script.ts

# Better: Fix the source's SSL certificate
# Or use HTTP if available (less secure)

Cache Issues

Stale cache

Issue: API returns old/outdated results.

Solution:

1. Check cache age:

const response = await fetch('/compile', {...});
console.log(response.headers.get('X-Cache-Age'));  // Seconds

2. Force cache refresh: Add a unique parameter:

const config = {
  name: "My List",
  version: new Date().toISOString(),  // Forces new cache key
  sources: [...]
};

3. Cache TTL:

• Default: 1 hour
• Max: 24 hours

Cache miss rate high

Issue:

X-Cache-Status: MISS

Most requests miss cache.

Solution: Use consistent configuration:

// BAD - timestamp changes every time
const config = {
  name: "My List",
  version: Date.now().toString(),  // Always different!
  sources: [...]
};

// GOOD - stable configuration
const config = {
  name: "My List",
  version: "1.0.0",  // Static version
  sources: [...]
};

Compressed cache errors

Error:

DecompressionError: Invalid compressed data

Solution: Clear cache and recompile:

// Cache will be automatically rebuilt
// If persistent, file a GitHub issue

Deployment Issues

deno: not found error during deployment

Error:

Executing user deploy command: deno deploy
/bin/sh: 1: deno: not found
Failed: error occurred while running deploy command

Cause: This error occurs when Cloudflare Pages is configured with deno deploy as the deploy command. This project uses Cloudflare Workers (not Deno Deploy) and should use wrangler deploy instead.

Solution: Update your Cloudflare Pages dashboard configuration:

1. Go to your Pages project settings
2. Navigate to "Builds & deployments"
3. Under "Build configuration":
   • Set Build command to: npm install
   • Set Deploy command to: (leave empty)
   • Set Build output directory to: public
   • Set Root directory to: (leave empty)
4. Save changes and redeploy

For detailed instructions, see the Cloudflare Pages Deployment Guide.

Why this happens:

• This is a Deno-based project, but it deploys to Cloudflare Workers, not Deno Deploy
• The build environment has Node.js/pnpm but not Deno installed
• Wrangler handles the deployment automatically

Cloudflare Worker deployment fails

Error:

Error: Worker exceeded memory limit

Solutions:

1. Check bundle size:

du -h dist/worker.js
# Should be < 1MB

2. Minify code:

deno bundle --minify src/worker.ts dist/worker.js

3. Remove unused imports:

// BAD
import * as everything from '@jk-com/adblock-compiler';

// GOOD
import { compile, FilterCompiler } from '@jk-com/adblock-compiler';

Worker KV errors

Error:

KV namespace not found

Solution: Ensure KV namespace is bound in wrangler.toml:

[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"

Create namespace:

wrangler kv:namespace create CACHE

Environment variables not set

Error:

ReferenceError: CACHE is not defined

Solution: Add bindings in wrangler.toml:

[env.production]
vars = { ENVIRONMENT = "production" }

[[env.production.kv_namespaces]]
binding = "CACHE"
id = "production-kv-id"

Platform-Specific Issues

Deno issues

Issue: Import map not working

Solution:

# Use deno.json, not import_map.json
# Ensure deno.json is in project root

Issue: Type errors

Solution:

# Clear Deno cache
rm -rf ~/.cache/deno
deno cache --reload src/main.ts

Node.js issues

Issue: ES modules not supported

Solution: Add to package.json:

{
    "type": "module"
}

Or use .mjs extension:

mv index.js index.mjs

Issue: CommonJS require() not working

Solution:

// Use dynamic import
const { compile } = await import('@jk-com/adblock-compiler');

// Or convert to ES modules

Browser issues

Issue: Module not found

Solution: Use a bundler (esbuild, webpack):

npm install -D esbuild
npx esbuild src/main.ts --bundle --outfile=dist/bundle.js

Issue: CORS with local files

Solution: Run a local server:

# Python
python -m http.server 8000

# Deno
deno run --allow-net --allow-read https://deno.land/std/http/file_server.ts

# Node
npx serve .

Getting Help

Enable debug logging

// Set environment variable
Deno.env.set('DEBUG', 'true');

// Or in .env file
DEBUG = true;

Collect diagnostics

# System info
deno --version
node --version

# Network test
curl -I https://adblock-compiler.jayson-knight.workers.dev/api

# Permissions test
deno run --allow-net test.ts

Report an issue

Include:

1. Error message (full stack trace)
2. Minimal reproduction code
3. Configuration file (sanitized)
4. Platform/version info
5. Steps to reproduce

GitHub Issues: https://github.com/jaypatrick/adblock-compiler/issues

Community support

• Documentation: README.md
• API Reference: docs/api/README.md
• Examples: docs/guides/clients.md
• Web UI: https://adblock-compiler.jayson-knight.workers.dev/

Quick Fixes Checklist

• Updated to latest version?
• Cleared cache? (rm -rf ~/.cache/deno or rm -rf node_modules)
• Correct permissions? (--allow-net --allow-read)
• Valid configuration? (name + sources required)
• Network connectivity? (curl -I <source-url>)
• Rate limits respected? (60 req/min)
• Checked GitHub issues? (Someone may have solved it)

Still stuck? Open an issue with full details!