ArchiveBox/ArchiveBox · error · ValueError

Depth must be 0-4

Error message

Depth must be 0-4

What it means

The 'archivebox add' CLI validates its depth parameter and only allows values 0 through 4 (0 = single URL, 1-4 = recursive crawl depth). Passing any other integer raises ValueError 'Depth must be 0-4'. This bounds the recursive link-crawl so a bad flag cannot trigger unbounded crawling.

Source

Thrown at archivebox/cli/archivebox_add.py:104

    from rich import print

    depth = int(depth)
    max_urls = int(max_urls or 0)
    crawl_max_size = parse_filesize_to_bytes(crawl_max_size)
    crawl_timeout = int(crawl_timeout or 0)
    snapshot_max_size = parse_filesize_to_bytes(snapshot_max_size)
    from archivebox.config.permissions import USER, HOSTNAME
    from archivebox.config.common import get_config

    config_overrides = dict(config or {})
    runtime_config = get_config()
    crawl_max_concurrent_snapshots_override = crawl_max_concurrent_snapshots is not None
    if crawl_max_concurrent_snapshots is None:
        crawl_max_concurrent_snapshots = runtime_config.CRAWL_MAX_CONCURRENT_SNAPSHOTS
    crawl_max_concurrent_snapshots = int(crawl_max_concurrent_snapshots)

    if depth not in (0, 1, 2, 3, 4):
        raise ValueError("Depth must be 0-4")
    if max_urls < 0:
        raise ValueError("max_urls must be >= 0")
    if crawl_max_size < 0:
        raise ValueError("crawl_max_size must be >= 0")
    if crawl_timeout < 0:
        raise ValueError("crawl_timeout must be >= 0")
    if snapshot_max_size < 0:
        raise ValueError("snapshot_max_size must be >= 0")
    if crawl_max_concurrent_snapshots < 1:
        raise ValueError("crawl_max_concurrent_snapshots must be >= 1")

    # import models once django is set up
    from archivebox.crawls.models import Crawl
    from archivebox.base_models.models import get_or_create_system_user_pk
    from archivebox.personas.models import Persona
    from archivebox.misc.logging_util import printable_filesize
    from archivebox.misc.system import get_dir_size
    from archivebox.core.shutdown_util import foreground_parent_watchdog, foreground_shutdown_signals

View on GitHub (pinned to 74564b2822)

Solutions

1. Use --depth between 0 and 4 (use 0 for no recursion, 1-4 for link-following depth)
2. Clamp the value in calling code: depth = max(0, min(4, depth))
3. Check archivebox add --help for the documented range

Example fix

// before
archivebox add --depth=5 'https://example.com'
// after
archivebox add --depth=4 'https://example.com'

depth = int(depth)
if not 0 <= depth <= 4:
    raise SystemExit('depth must be 0-4')

def is_valid_depth(d) -> bool:
    return isinstance(d, int) and 0 <= d <= 4

try:
    archivebox_add(depth=depth, urls=urls)
except ValueError as e:
    if 'Depth must be 0-4' in str(e):
        archivebox_add(depth=min(max(depth, 0), 4), urls=urls)

When it happens

Trigger: archivebox add --depth=5, --depth=-1, or programmatically calling add(..., depth=N) where N is outside {0,1,2,3,4}; passing a non-castable depth won't reach this check but any int outside range will.

Common situations: Users assuming depth is unbounded or 1-indexed differently; scripts copying an example with --depth=5; automation constructing depth from config values like 'unlimited' mapped incorrectly to a large number.

Related errors

• max_urls must be >= 0
• crawl_max_size must be >= 0
• crawl_timeout must be >= 0
• str(err)
• At least one URL is required

AI-assisted analysis of ArchiveBox/ArchiveBox@74564b2822 (2026-08-28). Data as JSON: /api/errors/a2318134b8744e23. Report an issue: GitHub.