influxdata/influxdb · error · CatalogError

cannot parse token permission

Error message

cannot parse token permission, {0}

What it means

This error occurs when a permission string attached to a token cannot be parsed into a catalog permission. The token permissions are stored as strings and deserialized into the `Permission` type; an unrecognized or malformed permission string triggers this error with the bad value in the message.

Solutions

1. Use only documented permission names for the token (e.g. via the influxdb3 CLI token creation flags)
2. Inspect the message for the offending permission string and correct it
3. If migrating from an old catalog, regenerate tokens rather than copying permission strings
4. Upgrade/re-sync the catalog if the permission scheme changed between versions

Example fix

// before
TokenInfo::new("my-token", &["read:bucket:mydb"]);
// after
TokenInfo::new("my-token", &["read:buckets"]);
// use the Permission enum / documented permission strings

fn permissions_parse(ps: &[&str]) -> Result<(), String> {
    ps.iter().map(|p| p.parse::<Permission>())
      .collect::<Result<Vec<_>, _>>().map(|_| ()).map_err(|e| e.to_string())
}

match result {
    Err(CatalogError::CannotParsePermissionForToken(p)) => eprintln!("fix permission string: {p}"),
    r => r,
}

When it happens

Trigger: Creating or updating an API token whose permission list contains a string that does not match any known permission; loading a catalog file that contains hand-edited or legacy permission strings.

Common situations: Hand-editing the catalog/Neo4j-style stored token definitions; copying permission names from older InfluxDB versions; typos like `read:buckets` vs the InfluxDB 3 permission naming scheme.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• cannot delete operator token
• missing admin token, cannot update
• token hash already exists
• token name already exists
• Authorization error

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/48b559c15b6a72b7. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_catalog/src/error.rs:279

        trigger_name: String,
    },

    #[error("failed to parse trigger from {}", trigger_spec)]
    ProcessingEngineTriggerSpecParseError { trigger_spec: String },

    #[error("last cache size must be greater than 0")]
    InvalidLastCacheSize,

    #[error("failed to parse trigger from {trigger_spec}{}", .context.as_ref().map(|context| format!(": {context}")).unwrap_or_default())]
    TriggerSpecificationParseError {
        trigger_spec: String,
        context: Option<String>,
    },

    #[error("invalid error behavior {0}")]
    InvalidErrorBehavior(String),

    #[error("cannot parse token permission, {0}")]
    CannotParsePermissionForToken(String),

    #[error("token name already exists, {0}")]
    TokenNameAlreadyExists(String),

    #[error("token hash already exists")]
    TokenHashAlreadyExists,

    #[error("missing admin token, cannot update")]
    MissingAdminTokenToUpdate,

    #[error("cannot delete internal db")]
    CannotDeleteInternalDatabase,

    #[error("cannot modify internal db")]
    CannotModifyInternalDatabase,

    #[error("tried to stop a node ({node_id}) that is already stopped")]

View on GitHub (pinned to 06200ef96b)