Troubleshooting
Most ALX failures come from mismatched input, normalization, authorization, or verification context. Start with the failing layer and compare the exact values supplied to the verifier.
Find the Failing Layer
| Result | Check |
|---|---|
SyntaxError from parseStrictJson() | The JSON text is malformed, contains a duplicate member, or has trailing data. |
validateBlock() throws ALX_SCHEMA_INVALID | The record must contain exactly the five Block fields. |
validateBlock() throws ALX_UNSUPPORTED_VERSION | protocolVersion must be the string "1". |
ALX_INVALID_HASH | Use 0x followed by 64 hexadecimal characters; parentHashes must be an array of strings. |
ALX_TOO_MANY_PARENTS | A Block declares at most 256 distinct parents. |
ALX_CANONICALIZATION_* | The content contains a value outside the ALX value model. Canonicalization lists each rejection. |
Block hash mismatch (ALX_BLOCK_HASH_MISMATCH) | Recompute from the original content and normalized parents. |
Content hash mismatch (ALX_CONTENT_HASH_MISMATCH) | Confirm the content has not changed and canonicalization matches. |
ok: false while both match values are true | The stored parentHashes are not normalized or contain the Block's own blockHash. Check parentsCanonical and selfRef. |
| Different hashes for the same content in two languages | Compare the canonical bytes. Cross-Language Requirements lists common divergences. |
Graph incomplete, hashes listed in missingParents | Load the referenced Blocks, or report the Graph as incomplete. |
Cycle detected (ALX_GRAPH_CYCLE) | Treat the Graph as invalid. Correctly derived hashes cannot form a cycle without a Keccak-256 collision, so run validateBlock() on each Block in the cycle to find the record whose blockHash does not match its content. |
| Signature mismatch | Confirm the attestation algorithm, attester, blockHash, and timestamp. For an EIP-712 protocol request, confirm the signer, domain, chain ID, contract, and typed-data fields. |
| Merkle proof failed | Confirm the Merkle root hash, leaf, sibling values, and sorted-pair algorithm. |
| Commitment transaction rejected | AlreadyAnchored: the value is already recorded; read anchoredAt and anchoredBy. BatchTooSmall or BatchTooLarge: anchorBatch needs 2 to 256 values. Confirm chain ID 8453 and the address on the ALX on Base page. |
Recover from a Failure
Preserve the original input and expected output before changing data. Reproduce the failure with synthetic values, then rerun the relevant conformance or negative test. Correcting a Block's content or parents creates a new Block with a new blockHash.
When to Reject
Reject malformed hashes, unsupported canonicalization values, mismatched identities, invalid signatures, unauthorized submissions, and failed proofs. Report an incomplete Graph as missing lineage, separately from an invalid Graph.