risingwavelabs/risingwave · critical

Failed to retrieve fragment description: fragment

Error message

Failed to retrieve fragment description: fragment {} (job_id {}) not found in shared actor info

What it means

get_fragment_desc_by_id reads the fragment row from the database, then looks up the live fragment/actor info in the in-memory shared actor info cache. The error (a panic via unwrap_or_else) means the DB still has the fragment but the shared-actor-info snapshot no longer holds it, i.e. cache and database are out of sync.

Solutions

1. Verify the streaming job still exists (not being dropped) before querying its fragments
2. Retry after a short delay if a concurrent DDL may be in flight
3. Inspect meta node logs for shared actor info eviction/rebuild events around the failure time
4. If reproducible after restart, check that actor deployment completion persists shared fragment info before responding to the DDL

Example fix

// before
let info = shared_actor_infos().read_guard().get_fragment(fid).unwrap_or_else(|| panic!(...));
// after
let info = shared_actor_infos().read_guard().get_fragment(fid).ok_or_else(|| MetaError::fragment_not_found(fid))?;

// caller: check job still exists before fetching fragments
let exists = StreamingJob::find_by_id(job_id).one(&db).await?.is_some();

fn fragment_in_shared_info(guard: &SharedActorInfos, fid: FragmentId) -> bool { guard.get_fragment(fid).is_some() }

match get_fragment_desc_by_id(job_id).await { Ok(d) => d, Err(e) if e.to_string().contains("not found in shared actor info") => retry_or_skip(job_id), Err(e) => return Err(e) }

When it happens

Trigger: Calling FragmentManager::get_fragment_desc_by_id for a fragment_id whose fragment exists in the fragments table but was evicted/never inserted into shared actor info — e.g. querying during job deletion, or before the job's actors were published to the cache.

Common situations: Frontend fetching fragment descriptions while a DDL (drop/backfill cancel) is concurrently removing the job's actors; querying right after meta recovery when shared actor info was rebuilt from incomplete data; debugging tools hitting fragments of already-dropped streaming jobs.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• expected exactly one mview fragment for job
• failed to parse relation definition
• fragment not found in shared actor info
• fragments not found
• internal error: entered unreachable code

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/745c94194ac0e5a9. Report an issue: GitHub.

Appendix: source

Thrown at src/meta/src/controller/fragment.rs:582

        let upstreams: Vec<_> = upstream_entries
            .into_iter()
            .map(|(source_id, _)| source_id)
            .collect();

        let root_fragment_map = find_fragment_no_shuffle_dags_detailed(&inner.db, &[fragment_id])
            .await
            .map(Self::collect_root_fragment_mapping)?;
        let root_fragments = root_fragment_map
            .get(&fragment_id)
            .cloned()
            .unwrap_or_default();

        let info = self.env.shared_actor_infos().read_guard();
        let SharedFragmentInfo { actors, .. } = info
            .get_fragment(fragment_model.fragment_id as _)
            .unwrap_or_else(|| {
                panic!(
                    "Failed to retrieve fragment description: fragment {} (job_id {}) not found in shared actor info",
                    fragment_model.fragment_id,
                    fragment_model.job_id
                )
            });

        let parallelism_policy = Self::format_fragment_parallelism_policy(
            fragment_model.distribution_type,
            fragment_model.parallelism.as_ref(),
            job_parallelism.as_ref().map(|(parallelism, _)| parallelism),
            job_parallelism
                .as_ref()
                .and_then(|(_, strategy)| strategy.as_deref()),
            &root_fragments,
        );

        let fragment = FragmentDesc {
            fragment_id: fragment_model.fragment_id,

View on GitHub (pinned to 6469eb736d)