clockworklabs/SpacetimeDB · error

Manual migration plans are not yet supported for pretty prin

Error message

Manual migration plans are not yet supported for pretty printing.

What it means

When schema changes cannot be handled automatically, SpacetimeDB can produce a Manual migration plan (generated Rust migration code). MigratePlan::pretty_print only implements the Auto variant; asking it to render a Manual plan bails with this message.

Source

Thrown at crates/schema/src/auto_migrate.rs:75

        }
    }

    pub fn breaks_client(&self) -> bool {
        match self {
            //TODO: fix it when support for manual migration plans is added.
            MigratePlan::Manual(_) => true,
            MigratePlan::Auto(plan) => plan
                .steps
                .iter()
                .any(|step| matches!(step, AutoMigrateStep::DisconnectAllUsers)),
        }
    }

    pub fn pretty_print(&self, style: PrettyPrintStyle) -> anyhow::Result<String> {
        use PrettyPrintStyle::*;
        match self {
            MigratePlan::Manual(_) => {
                anyhow::bail!("Manual migration plans are not yet supported for pretty printing.")
            }

            MigratePlan::Auto(plan) => match style {
                NoColor => {
                    let mut fmt = TermColorFormatter::new(ColorScheme::default(), termcolor::ColorChoice::Never);
                    format_plan(&mut fmt, plan).map(|_| fmt.to_string())
                }
                AnsiColor => {
                    let mut fmt = TermColorFormatter::new(ColorScheme::default(), termcolor::ColorChoice::AlwaysAnsi);
                    format_plan(&mut fmt, plan).map(|_| fmt.to_string())
                }
            }
            .map_err(|e| anyhow::anyhow!("Failed to format migration plan: {e}")),
        }
    }
}

/// A migration policy that determines whether a module update is allowed to break client compatibility.

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Use the non-pretty output path: write the manual migration module to a file instead of printing it to the terminal.
2. Refactor the schema change into additive, auto-migratable steps (add new columns/tables instead of rewriting) so the plan stays Auto and pretty printing works.

# detect a manual plan before asking for pretty output:
# if the tooling reports the plan is Manual, route to file output instead of
# the pretty-print/preview path; only Auto plans support pretty printing

match plan.pretty_print(style) {
    Err(e) if e.to_string().contains("Manual migration plans") => {
        // write the generated manual migration module to a file instead
    }
    other => other,
}

When it happens

Trigger: Requesting a human-readable dump of a migration plan that turned out to be MigratePlan::Manual, i.e. the schema diff contained changes the auto-migrator cannot express as auto steps.

Common situations: Inspecting a plan for a publish that includes incompatible changes (e.g. column type rewrites requiring data migration); running plan-preview tooling on a large schema refactor.

Related errors

• could not serialize result: object had neither a `ok` nor an
• Tried to read ${n} byte(s) at relative offset ${this.offset}
• Cannot semijoin a table to itself
• Cannot extract table name from query
• Cannot extract accessor name from query

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/7ce9c8d59b4329fc. Report an issue: GitHub.