ArchiveBox/ArchiveBox · error · Exception

Binary {self.binary.name} installation failed

Error message

Binary {self.binary.name} installation failed

What it means

Raised by ArchiveBox's BinaryMachine state machine (archivebox/machine/models.py:2672) when a binary-install transition fails. Before raising, the code increments the binary's health stats with success=False, so the failure is recorded, then aborts the transition so the binary remains in the 'queued' state rather than 'installed'. It is a plain Exception used as a state-machine abort signal.

Source

Thrown at archivebox/machine/models.py:2672

        # Check if installation succeeded by looking at updated status
        # Note: Binary.run() updates self.binary.status internally but doesn't refresh our reference
        self.binary.refresh_from_db()

        if self.binary.status != Binary.StatusChoices.INSTALLED:
            # Installation failed - abort transition, stay in queued
            rprint(f"[red]      ❌ BinaryMachine - {self.binary.name} installation failed, retrying later[/red]", file=sys.stderr)

            # Bump retry_at to try again later
            self.binary.update_and_requeue(
                retry_at=timezone.now() + timedelta(seconds=300),  # Retry in 5 minutes
                status=Binary.StatusChoices.QUEUED,  # Ensure we stay queued
            )

            # Increment health stats for failure
            self.binary.increment_health_stats(success=False)

            # Abort the transition - this will raise an exception and keep us in queued
            raise Exception(f"Binary {self.binary.name} installation failed")

        rprint(f"[cyan]      ✅ BinaryMachine - {self.binary.name} installed successfully[/cyan]", file=sys.stderr)

    @installed.enter
    def enter_installed(self):
        """Binary installed successfully."""
        self.binary.update_and_requeue(
            retry_at=None,
            status=Binary.StatusChoices.INSTALLED,
        )

        # Increment health stats
        self.binary.increment_health_stats(success=True)


# =============================================================================
# Process State Machine
# =============================================================================

View on GitHub (pinned to 74564b2822)

Solutions

1. Read the install log lines just above the error to see the real failure, then fix that root cause
2. Re-run `archivebox install` (the binary stays in queued state and can be retried) after network/dependency fixes
3. Install the dependency via your system package manager (apt/brew) so the installer detects an existing binary
4. Set a custom binary path env/config (e.g. CHROMIUM_BINARY) to point at an existing executable and skip install

Example fix

# before
archivebox run   # fails: Binary chromium installation failed
# after
sudo apt-get install -y chromium  # or fix proxy, then
archivebox install && archivebox run

import shutil
if not (shutil.which('chromium') or shutil.which('google-chrome')):
    # ensure network + system deps available before running install
    subprocess.run(['archivebox', 'install'], check=True)

def is_binary_installed(name: str) -> bool:
    return shutil.which(name) is not None

try:
    subprocess.run(['archivebox', 'install'], check=True)
except Exception as e:
    if f'Binary {name} installation failed' in str(e):
        install_system_package(name)  # fall back to apt/brew, then retry

When it happens

Trigger: A binary dependency (e.g. chromium, wget, singlefile) fails to download or install during `archivebox install` / `archivebox init --install`, or when the archive runner auto-installs a missing extractor binary: bad network, missing apt/brew dependency, checksum mismatch, or the installer hook exiting non-zero.

Common situations: Offline or proxied environments blocking binary downloads; missing system packages (e.g. chromium deps); unsupported OS/arch with no prebuilt binary; stale pip/curl versions; permission errors writing to the bin dir.

Related errors

• 2
• Couldn't import Django. Are you sure it's installed and avai
• Pass either records or stdin, not both
• Unknown argument(s): {', '.join(unknown)}
• Missing required parameter: name

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