{"record":{"id":"1db979940eff1dc2","repo":"rustfs/rustfs","slug":"runnernotinstalled","errorCode":"RunnerNotInstalled","errorMessage":"backfill runner is not installed","messagePattern":"backfill runner is not installed","errorType":"error_code","errorClass":"BackfillError","httpStatus":null,"severity":"error","filePath":"rustfs/src/on_demand_migration/backfill.rs","lineNumber":352,"sourceCode":"#[derive(Debug, thiserror::Error)]\npub enum BackfillError {\n    #[error(\"backfill checkpoint is malformed: {0}\")]\n    Malformed(String),\n    #[error(\"unsupported backfill checkpoint format version {found} (this build supports {supported})\")]\n    UnsupportedFormatVersion { found: u32, supported: u32 },\n    #[error(\"a backfill job is already running for bucket {bucket} (job {job_id}, owner {owner})\")]\n    AlreadyRunning { bucket: String, job_id: Uuid, owner: String },\n    #[error(\"no backfill job recorded for bucket {0}\")]\n    NotFound(String),\n    #[error(\"bucket {0} has no usable on-demand migration state on this node\")]\n    Unavailable(String),\n    #[error(\"bucket {0} has no on-demand migration config\")]\n    NotConfigured(String),\n    #[error(\"backfill lease lock for bucket {0} is busy\")]\n    LeaseBusy(String),\n    #[error(\"backfill checkpoint for bucket {0} changed concurrently\")]\n    Conflict(String),\n    #[error(\"backfill runner is not installed\")]\n    RunnerNotInstalled,\n    #[error(transparent)]\n    Storage(#[from] StorageError),\n}\n\n/// Current local version of a key as the skip policy sees it.\n#[derive(Clone, Debug, PartialEq, Eq)]\npub struct LocalBackfillObject {\n    pub size: u64,\n    /// The `odm-source-etag` provenance value when present, else the local ETag.\n    pub source_etag: Option<String>,\n}\n\n/// Shared report of a new or coalesced pull; absent only when not admitted.\npub type PullReport = Option<super::pull::QueuedPullReport>;\n\n/// Everything the job needs from its bucket, so the loop can run against a\n/// mock in unit tests. Production: [`BucketBackfillContext`].","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/rustfs/rustfs/blob/5dca076efed96e7b842de07c4c2111035ae7c7a2/rustfs/src/on_demand_migration/backfill.rs#L334-L370","documentation":"BackfillError::RunnerNotInstalled is thrown when a backfill operation is requested but the process has no backfill runner installed — i.e. the runtime wiring (the component that actually executes migration work) was never registered in this node/binary. This is an assembly/initialization bug, not a runtime data problem.","triggerScenarios":"Invoking a backfill API (start/resume/status-advance) on a node or in a test/binary where the runner was never registered via the runner-install hook before use.","commonSituations":"Embedding the on_demand_migration module in a custom binary and forgetting to install the runner; calling backfill endpoints against a node built without migration support; unit tests exercising the API without a mock runner.","solutions":["Install the backfill runner during process initialization before any backfill call.","Confirm you are targeting the full rustfs binary that bundles the migration runner, not a stripped build.","In tests, register a test/mock runner before exercising backfill APIs."],"exampleFix":"// before\nbackfill::start(bucket).await?; // RunnerNotInstalled\n// after\nbackfill::install_runner(my_runner).await?;\nbackfill::start(bucket).await?;","handlingStrategy":"type-guard","validationCode":"if !backfill::runner_installed() { return Err(anyhow!(\"backfill runner not installed\")); }","typeGuard":"fn runner_ready() -> bool { backfill::runner_installed() }","tryCatchPattern":null,"preventionTips":["Install the runner in process init before any migration API use.","Add a startup assertion that the runner is installed in binaries exposing backfill APIs."],"tags":["initialization","missing-dependency","migration","backfill"],"backgroundTag":"module-init-failed","analyzedSha":"5dca076efed96e7b842de07c4c2111035ae7c7a2","analyzedAt":"2026-09-06T05:54:05.891Z","contentChangedAt":"2026-09-06T05:54:05.891Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}