Documentation Index
Fetch the complete documentation index at: https://docs.blindference.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Troubleshooting
Frontend Issues
”Failed to fetch” during CoFHE encryption
Symptoms: Browser console shows Failed to fetch or NetworkError during encryption.
Causes:
- Stale IndexedDB cache in
@cofhe/sdk
- ZK proof verifier endpoint unavailable
- Rate limiting
Fix:
// 1. Clear browser cache and hard reload
// Ctrl+Shift+R (Chrome/Windows)
// Cmd+Shift+R (Chrome/Mac)
// 2. Remove Vite cache
rm -rf node_modules/.vite
// 3. Ensure fheKeyStorage: null in config
const client = await cofheClient.create({
fheKeyStorage: null, // Critical!
// ...
});
// 4. Add retry logic
async function encryptWithRetry(value, retries = 3) {
for (let i = 0; i < retries; i++) {
try {
return await client.encryptInputs().execute(value);
} catch (e) {
if (i === retries - 1) throw e;
await new Promise(r => setTimeout(r, 2000 * (i + 1)));
}
}
}
Browser freezes during encryption
Symptoms: Browser becomes unresponsive for 10-30 seconds after submitting.
Cause: CoFHE ZK proof generation runs on main thread (useWorkers: false).
Fix: Show a warning to the user:
function showZkWarning() {
const warning = document.createElement('div');
warning.innerHTML = `
<div style="position:fixed;top:0;left:0;right:0;background:#ff9800;color:black;padding:10px;text-align:center;z-index:9999">
⚠️ Generating zero-knowledge proof... Browser may be unresponsive for 10-30s. Do not refresh.
</div>
`;
document.body.appendChild(warning);
return () => warning.remove();
}
storeKey is called before user interaction, or wallet not connected.
Fix:
// Ensure wallet is connected first
if (!walletClient.account) {
await walletClient.connect();
}
// Call storeKey after user clicks submit button
// (must be inside user gesture handler)
button.addEventListener('click', async () => {
await storeKey(encHigh.ctHash, encLow.ctHash);
});
ICL Issues
”not enough active nodes available for the requested quorum”
Symptoms: GET /v1/inference/quorum-preview returns 400 with this message.
Cause: Fewer than 3 nodes (1 leader + 2 verifiers) are active in the pool.
Fix:
# Check active node count
curl -s http://127.0.0.1:9000/v1/nodes/active | python3 -m json.tool | grep -c "operator_address"
# If < 3, start more nodes or check existing nodes
# Check node logs for attestation/heartbeat failures
ICL MongoDB connection fails
Symptoms: ICL falls back to in-memory persistence.
Cause: MongoDB Atlas URI incorrect, network issues, or IP not allowlisted.
Fix:
# Test MongoDB connection
mongosh "mongodb+srv://..."
# Check Atlas IP allowlist
# Add your server IP to Atlas Network Access
# Use in-memory fallback for local dev (automatic)
Node Issues
”Missing CoFHE key handles — cannot decrypt prompt”
Symptoms: Job aborts after claiming.
Cause: claim_task returned empty handles or claim failed.
Fix:
# Check ICL logs for claim errors
grep "task/claim" icl.log
# Verify node is properly registered
curl $BLF_ICL_ENDPOINT/v1/nodes/active | grep YOUR_ADDRESS
“Too Many Requests” from Alchemy
Symptoms: CoFHE operations fail with rate limit errors.
Cause: Alchemy free tier limits requests.
Fix:
# Use dedicated RPC endpoint
export BLF_COFHE_ENDPOINT=https://arb-sepolia.g.alchemy.com/v2/YOUR_DEDICATED_KEY
# Or use Fhenix Helios endpoint
export BLF_COFHE_ENDPOINT=https://api.helios.fhenix.zone
Contract Issues
”storeKey transaction reverted”
Symptoms: MetaMask shows transaction failed.
Causes:
- Insufficient gas
- Wrong PromptKeyStore address
- Invalid ciphertext handles
Fix:
// Check you have Sepolia ETH for gas
// Ensure correct contract address:
const PROMPT_KEY_STORE = '0x1E22dD12f448B15f1Ca8560fB6B4463834FaAf73';
// Verify handles are valid uint256
console.log(typeof kpHighHandle, kpHighHandle); // Should be string or BigNumber
“ResultRegistry not found”
Symptoms: ICL cannot commit results on-chain.
Cause: Wrong ResultRegistry address or contract not deployed.
Fix:
# Verify contract is deployed
curl -s "https://api-sepolia.arbiscan.io/api?module=contract&action=getabi&address=0xCebd831eCd00915E299b8Ef2666cAbf942dc7150&format=raw" | head -c 100
# Should return ABI JSON, not "NOTOK"
Network Issues
Cannot connect to Arbitrum Sepolia
Symptoms: Transactions fail, RPC errors.
Fix:
# Test RPC endpoint
curl -X POST https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
# Should return: {"jsonrpc":"2.0","id":1,"result":"0x..."}
IPFS download timeout
Symptoms: Nodes cannot download prompt/output blobs.
Fix:
# Test IPFS gateway
curl -s https://gateway.pinata.cloud/ipfs/QmTest123 | head -c 100
# Try alternative gateways:
# https://ipfs.io/ipfs/{cid}
# https://cloudflare-ipfs.com/ipfs/{cid}
Getting Help
If none of the above fixes work:
-
Collect logs:
- Frontend: Browser console logs (F12 → Console)
- ICL:
tail -n 1000 icl.log
- Node:
tail -n 1000 ~/.blindference/node.log
-
Open an issue:
-
Join Discord: Blindference Community
