GuidesTroubleshooting Guide

Troubleshooting Guide

Common issues and solutions for Bloqr Compiler.

Troubleshooting Guide

Common issues and solutions for Bloqr Compiler.

Table of Contents

Installation Issues

Package not found on JSR

Error: 
error: JSR package not found: @bloqr/compiler

Solution: Use npm import as fallback:

import { compile } from 'npm:@bloqr/compiler';

Or install via npm:

npm install @bloqr/compiler

Deno version incompatibility

Error: 
error: Unsupported Deno version

Solution: Bloqr 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
  1. 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'],
};
  1. 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
  1. Use streaming for large files: 
// Process sources in chunks
const config = {
    sources: smallBatch, // Process 10-20 sources at a time
    transformations: ['Compress', 'Deduplicate'],
};
  1. 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
  1. Use batch API for multiple lists: 
// Compile in parallel
POST /compile/batch
{
  "requests": [
    { "id": "list1", "configuration": {...} },
    { "id": "list2", "configuration": {...} }
  ]
}
  1. Optimize transformations: 
// Minimal transformations for speed
transformations: [
    'RemoveComments',
    'Deduplicate',
    'RemoveEmptyLines',
];

// Remove expensive transformations like:
// - Validate (checks every rule)
// - ConvertToAscii (processes every character)
  1. 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://api.bloqr.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
  1. Circuit breaker will retry:
  • Automatic retry with exponential backoff
  • Up to 3 attempts
  • Then source is temporarily disabled
  1. 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
  1. Force cache refresh: Add a unique parameter:
const config = {
  name: "My List",
  version: new Date().toISOString(),  // Forces new cache key
  sources: [...]
};
  1. 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
  1. Minify code: 
deno bundle --minify src/worker.ts dist/worker.js
  1. Remove unused imports: 
// BAD
import * as everything from '@bloqr/compiler';

// GOOD
import { compile, FilterCompiler } from '@bloqr/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('@bloqr/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://api.bloqr.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/bloqr-systems/bloqr-compiler/issues

Community support

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!

Was this page helpful?