Skip to content

Troubleshooting

Consumer-side diagnostics for the gaiaftcl Python client.

FranklinClientError: Substrate database not found

FranklinClient.connect()
# FranklinClientError: Substrate database not found at
# /Users/.../Library/Application Support/GaiaFTCL/substrate.sqlite

Cause. The substrate daemon has not yet been started, or has been writing to a non-default path.

Fix.

  1. Verify the daemon is running on the same host: 
    pgrep -lf M8BTCSubstrateMiner
  2. If running but the database is elsewhere, pass an explicit path: 
    FranklinClient.connect(substrate_db_path=Path("/custom/path/substrate.sqlite"))
  3. If not running, start it per FRANKLIN_FIRST.

MeshLoaderError: Manifest not found for ...

load_from_mesh("gaiaftcl.bridges.numpy_bridge")
# MeshLoaderError: Manifest not found for gaiaftcl.bridges.numpy_bridge

Cause. The bridge's manifest has not been populated into the mesh cache.

Fix.

  1. Verify the cache root exists: 
    ls ~/.gaiaftcl/mesh_cache/gaiaftcl.bridges.numpy_bridge/
  2. If absent, fetch from the operator's federation distribution server (operator documents the source endpoint) or use the in-package bridge directly: 
    from gaiaftcl.bridges.numpy_bridge import leading_zero_histogram
  3. For multi-cell federations, set the cache root via GAIAFTCL_MESH_CACHE to point at the operator's shared mesh cache mirror.

MeshLoaderError: Federation verification failed for ...

Cause. The bridge's artifact hashes don't match the manifest's seal, or the manifest's witness hash doesn't match SHA-256(canonical_witness).

Fix.

  1. Re-fetch the manifest + artifacts from the operator's federation distribution.
  2. Check for in-transit corruption.
  3. If persistent, the federation seal may have drifted — surface to the operator.

ImportError: numpy is not installed

from gaiaftcl.bridges.numpy_bridge import leading_zero_histogram
leading_zero_histogram(rows)
# ImportError: numpy is not installed. Install with `pip install gaiaftcl[numpy]`.

Fix.

pip install gaiaftcl[numpy]
# or the equivalent for your bridge
pip install gaiaftcl[pandas, sklearn, biopython, rdkit, ase, pymatgen, root]

The base gaiaftcl package imports cleanly without optional bridge dependencies.

Bridge conversion error — cell.split('/') fails

Cause. A V160 row's projection_cells_canonical field is in an unexpected format.

Fix. Inspect the substrate row:

import sqlite3
conn = sqlite3.connect("file:" + str(Path.home() / "Library/Application Support/GaiaFTCL/substrate.sqlite") + "?mode=ro", uri=True)
conn.row_factory = sqlite3.Row
row = dict(conn.execute(
    "SELECT projection_cells_canonical FROM qc020_substrate_research_telemetry "
    "ORDER BY row_id DESC LIMIT 1"
).fetchone())
print(row["projection_cells_canonical"][:200])

The substrate-canonical format is ["num/den", "num/den", ...]. If your installed substrate writes a different shape, the substrate version may have drifted ahead of the client. Upgrade gaiaftcl or surface to the operator.

Federation verification fails

verify_signature_quintet(...) == False

Cause. Witness hash mismatch — substrate divergence, schema migration in progress, or row corruption.

Fix.

  1. Verify against a fresh heartbeat row: 
    hb = franklin.heartbeat_history(limit=1)[0]
ok = verify_signature_quintet(
    hb.canonical_witness, hb.witness_hash_sha256, hb.signature_quintet)
  2. If only specific rows fail, query their daemon_session_id — a daemon-restart transition may have left a partial write.
  3. If many recent rows fail, surface to the operator immediately. Federation cosignature is the substrate's verifiable seal; persistent failure is operationally significant.

Subscription stalls (no events yielded)

Cause. Substrate daemon stalled, or polling watermark hasn't moved past the seed.

Fix.

  1. Verify substrate is still composing measurements: 

    from gaiaftcl import FranklinClient
with FranklinClient.connect() as franklin:
    hbs = franklin.heartbeat_history(limit=3)
    for h in hbs: print(h.tick_at_iso)
    If tick_at_iso is stale (> 5 minutes ago), substrate daemon has stalled — surface to the operator.

  2. For V178 evidence (high-volume): subscribe inside an async task and ensure your consumer keeps up; backpressure in the consumer can make events appear stalled.

Socket connection issues (NATS path)

Cause. ~/.gaiaftcl/nats.toml is malformed or GAIAFTCL_NATS_URL points at an unreachable endpoint.

Fix.

  1. Verify reachability: 
    nc -z localhost 4222
  2. Check the NATS server is running. The substrate daemon's broadcaster needs the same endpoint.
  3. As a fallback, the Python client's polling path works without NATS — no configuration needed; events flow through SQLite tail-polling.

CLI not found after install

gaiaftcl-py heartbeat
# command not found

Fix. The gaiaftcl-py script is registered as a pip entry point. Ensure the install's bin directory is on PATH:

python3 -m pip show gaiaftcl | grep Location

Add the corresponding bin/ to your PATH or invoke as python3 -m gaiaftcl.cli.

Issues that persist: surface to the substrate operator. Substrate divergence is operationally significant; the federation seal is the verifiable invariant.

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 288d6414b7f7847f…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.