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

# General Troubleshooting

> Common issues across the Blindference stack

# 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**:

```javascript theme={null}
// 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:

```javascript theme={null}
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();
}
```

### MetaMask doesn't open for storeKey

**Symptoms**: Transaction doesn't prompt in MetaMask.

**Cause**: `storeKey` is called before user interaction, or wallet not connected.

**Fix**:

```javascript theme={null}
// 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```javascript theme={null}
// 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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:

1. **Collect logs**:
   * Frontend: Browser console logs (F12 → Console)
   * ICL: `tail -n 1000 icl.log`
   * Node: `tail -n 1000 ~/.blindference/node.log`

2. **Open an issue**:
   * Frontend/ICL/Contracts: [github.com/baync180705/blindference](https://github.com/baync180705/blindference)
   * Node runtime: [github.com/baync180705/Blindference-node](https://github.com/baync180705/Blindference-node)

3. **Join Discord**: [Blindference Community](https://discord.gg/blindference)