{"record":{"id":"a2318134b8744e23","repo":"ArchiveBox/ArchiveBox","slug":"depth-must-be-0-4","errorCode":null,"errorMessage":"Depth must be 0-4","messagePattern":"Depth must be 0-4","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"archivebox/cli/archivebox_add.py","lineNumber":104,"sourceCode":"    from rich import print\n\n    depth = int(depth)\n    max_urls = int(max_urls or 0)\n    crawl_max_size = parse_filesize_to_bytes(crawl_max_size)\n    crawl_timeout = int(crawl_timeout or 0)\n    snapshot_max_size = parse_filesize_to_bytes(snapshot_max_size)\n    from archivebox.config.permissions import USER, HOSTNAME\n    from archivebox.config.common import get_config\n\n    config_overrides = dict(config or {})\n    runtime_config = get_config()\n    crawl_max_concurrent_snapshots_override = crawl_max_concurrent_snapshots is not None\n    if crawl_max_concurrent_snapshots is None:\n        crawl_max_concurrent_snapshots = runtime_config.CRAWL_MAX_CONCURRENT_SNAPSHOTS\n    crawl_max_concurrent_snapshots = int(crawl_max_concurrent_snapshots)\n\n    if depth not in (0, 1, 2, 3, 4):\n        raise ValueError(\"Depth must be 0-4\")\n    if max_urls < 0:\n        raise ValueError(\"max_urls must be >= 0\")\n    if crawl_max_size < 0:\n        raise ValueError(\"crawl_max_size must be >= 0\")\n    if crawl_timeout < 0:\n        raise ValueError(\"crawl_timeout must be >= 0\")\n    if snapshot_max_size < 0:\n        raise ValueError(\"snapshot_max_size must be >= 0\")\n    if crawl_max_concurrent_snapshots < 1:\n        raise ValueError(\"crawl_max_concurrent_snapshots must be >= 1\")\n\n    # import models once django is set up\n    from archivebox.crawls.models import Crawl\n    from archivebox.base_models.models import get_or_create_system_user_pk\n    from archivebox.personas.models import Persona\n    from archivebox.misc.logging_util import printable_filesize\n    from archivebox.misc.system import get_dir_size\n    from archivebox.core.shutdown_util import foreground_parent_watchdog, foreground_shutdown_signals","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/ArchiveBox/ArchiveBox/blob/74564b28220090664f919479e82cbf454125fa34/archivebox/cli/archivebox_add.py#L86-L122","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use --depth between 0 and 4 (use 0 for no recursion, 1-4 for link-following depth)","Clamp the value in calling code: depth = max(0, min(4, depth))","Check archivebox add --help for the documented range"],"exampleFix":"// before\narchivebox add --depth=5 'https://example.com'\n// after\narchivebox add --depth=4 'https://example.com'","handlingStrategy":"validation","validationCode":"depth = int(depth)\nif not 0 <= depth <= 4:\n    raise SystemExit('depth must be 0-4')","typeGuard":"def is_valid_depth(d) -> bool:\n    return isinstance(d, int) and 0 <= d <= 4","tryCatchPattern":"try:\n    archivebox_add(depth=depth, urls=urls)\nexcept ValueError as e:\n    if 'Depth must be 0-4' in str(e):\n        archivebox_add(depth=min(max(depth, 0), 4), urls=urls)","preventionTips":["Clamp user/config depth to [0, 4] before invoking add","Treat depth 0 as 'no recursion' in UI copy so users don't pick 5+","Validate CLI flags with click.IntRange(0, 4) in wrappers"],"tags":["cli","validation","arguments","crawl"],"backgroundTag":"argument-out-of-range","analyzedSha":"74564b28220090664f919479e82cbf454125fa34","analyzedAt":"2026-08-28T23:56:51.556Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}