Troubleshooting

Common operational issues and their fixes. If your issue isn’t here, check the FAQ or ask on GitHub Discussions.

Installation

gem install confium fails to build the native extension

The Ruby gem compiles a Rust native extension at install time. You need:

  • Ruby ≥ 3.1
  • Rust stable 1.85+ (rustup default stable)
  • A C toolchain (cc, make)

Verify:

ruby --version    # >= 3.1
rustc --version   # >= 1.85
cc --version

If you see error: linking with cc failed, install Xcode CLI tools (macOS) or build-essential (Debian/Ubuntu).

cargo add confium-core pulls an old version

The workspace version is pinned in Cargo.toml. If you need the latest, use the git dependency:

[dependencies]
confium-core = { git = "https://github.com/confium/confium.git", branch = "main" }

WASM package fails to load in the browser

The @confium/confium-wasm package targets wasm32-unknown-unknown with wasm-bindgen. Make sure you:

  1. Initialize before use: await init();.
  2. Use the right import form for your bundler: 
    import init, { CompositeSignature } from "@confium/confium-wasm";
  3. Add the right Content-Type headers if self-hosting: application/wasm.

Ruby

Confium::ParseError when loading a PEM

Most common causes:

  • The PEM has Windows line endings (\r\n) but is being read with File.read in text mode (which can re-translate). Read in binary mode: File.open(path, "rb", &:read).
  • The PEM is missing begin/end markers. Verify: 
    -----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
  • The PEM is concatenated incorrectly. Each PEM block needs its own begin/end markers.

Confium::VerificationError from path validation

result = Confium::PKI::PathValidator.validate(
  leaf: cert, intermediates: [inter], root: root,
)
result.valid?   # => false
result.errors   # => [{ chain_index: 0, check: "signature", ... }]

Read result.errors — each error has chain_index, check, and details. Common causes:

  • check: "signature" — wrong root, expired cert, or revoked cert. Check the chain order: leaf, intermediates, root.
  • check: "validity" — cert is expired or not-yet-valid.
  • check: "name_constraints" — cert violates name constraints defined in root.

Confium::ThresholdError: insufficient quorum

The coordinator couldn’t reach threshold T. Check:

  • Are enough signers online? confium list-signers.
  • Are signers’ shares valid? Run confium signer self-test on each.
  • Is the policy correct? Read the deployment manifest’s [quorum] section.

Confium::PolicyViolationError: disallowed algorithm

The policy allow-list doesn’t include the algorithm. Update Confium::Policy.allowed_signature_algorithms or the deployment manifest’s [policy] section.

Rust

error[E0599]: no method named X found on type Y

Confium’s public API is concentrated in trait definitions. If a method isn’t found, you may be missing a trait import:

use confium_composite::VerifierCallback;  // bring the trait in

Compile errors with Scalar::from_repr

p256::Scalar::from_repr returns CtOption<Scalar>, not Option<Scalar>. Convert explicitly:

let scalar = Option::<Scalar>::from(Scalar::from_repr(bytes))
    .ok_or_else(|| MyError::InvalidScalar)?;

cargo test is slow

Some integration tests spawn coordinators and signers, which adds startup time. Run unit tests only:

cargo test --workspace --lib

WASM

RuntimeError: unreachable in browser console

The WASM module panics. Most common cause: missing initialization. Make sure await init(); runs before any other Confium call.

Bundle size is too large

The @confium/confium-wasm package has per-subsystem Cargo features. Tree-shake to just what you need:

# Cargo.toml (if you're building yourself)
[features]
verify-composite = []
verify-transparency = []
verify-attributes = []
verify-pki = []
default = ["verify-composite", "verify-transparency", "verify-attributes", "verify-pki"]

In npm, use the pre-built subset packages (@confium/confium-wasm-composite, etc.) when available.

Operations

Coordinator can’t reach signers

Check connectivity:

confium ping-signer --coordinator coord.internal:7443 --id director-1

Common causes:

  • Firewall blocking the coordinator’s QUIC port (default 7443).
  • Signer identity mismatch (the signer’s --identity doesn’t match the coordinator’s configured signer ID).
  • TLS certificate issues. The coordinator verifies signer certificates; if they’re expired or wrong-CA, signing fails.

Transparency log is growing unboundedly

That’s by design — the log is append-only. Add storage, or configure log rotation (which preserves the cryptographic chain by snapshotting roots periodically).

Signers joining late

The coordinator holds session state for in-flight sessions. If signers join after a session starts, they can still participate in subsequent rounds. Sessions time out after a configurable interval (default: 24 hours).

Witness detects divergence

This is the split-view attack detection firing. Investigate immediately:

  1. Compare tree heads between coordinators.
  2. Identify the divergent entries.
  3. Determine whether the divergence is malicious (operator compromise) or operational (split-brain, network partition).
  4. If malicious: switch to backup log; replay recent tree heads; initiate incident response.

Audit log shows unexpected signer identity

If signers in the audit record contains an identity you don’t recognize, the deployment manifest’s [[signers]] section may have a stale entry. Audit the manifest, remove the stale signer, and re-share to invalidate any share that signer may hold.

Plugin authoring

cfmp_* symbols missing from built library

Ensure crate-type = ["cdylib"] in [lib]:

[lib]
crate-type = ["cdylib"]

Then verify exports:

nm -D target/release/libmy_plugin.so | grep cfmp

Plugin loads but InterfaceNotSupported

The interface name in cfmp_query_interfaces doesn’t match what the host requested, or the version byte is higher than the host supports. Check:

  • Interface name spelling (case-sensitive).
  • Version byte — start with 0 and bump only when the contract changes.

PluginDependencyUnmet on load

A declared dependency is missing or out of range. Run confium list to see loaded plugins; check the version range in your Dependency::provider(...) call.

Build / CI

Site build fails with MDX errors

If you’re using @astrojs/mdx, JSX-trigger characters in content can break parsing. Specifically:

  • <word ...> in content is parsed as a JSX tag.
  • cfmp_<interface>_* in inline code triggers tag parsing.

Fix: escape < and > in code-block-adjacent content, or reword to avoid the pattern. See the MDX migration notes.

globLoader is not a function in Astro 7

The loader import changed in Astro 7. Use:

import { glob } from 'astro/loaders';

Not:

import { globLoader } from 'astro:content';

Could not resolve import for @layouts/*

The path alias must be declared in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@layouts/*": ["src/layouts/*"]
    }
  }
}

Where to get more help

See also