---

title: Python Wrappers — Troubleshooting

audience: industry_consumers

game: WIKI-PYTHON-WRAPPERS-TROUBLESHOOTING-001

---

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.*