Troubleshoot SGX attestation issues
Use this guide when an operator-backed localnet flow fails around identity, registration, or attestation rather than around public API usage.Prerequisites
- You already know the task is node-operations work.
- You are working on a localnet or enclave-capable runtime path.
- You can inspect host SGX device state and the environment passed to the operator binaries.
1. Confirm the localnet attestation mode
For the standard localnet path, confirm these conditions first:| Check | Expected result |
|---|---|
| report mode | REPORT_TYPE=SELF |
| debug posture | local debug builds must not be treated as DCAP mode |
| mode classification | you are on an enclave-capable operator path, not a trader or public API path |
2. Verify SGX device access on the host
Check that the SGX devices use the documented group-readable model rather than root-only access.| Device | Expected posture |
|---|---|
/dev/sgx_enclave | group-readable with the SGX access group |
/dev/sgx_provision | group-readable with the provisioning-device group |
/dev/sgx_vepc | group-readable with the SGX access group |
0660 plus group model, fix host access before you debug the application layer.
3. Verify PCCS and AESM reachability
Attestation flows depend on the platform services being reachable.| Dependency | Healthy posture |
|---|---|
| PCCS | reachable from the operator environment |
| AESM | running before the operator-backed workflow starts |
4. Verify enclave build flags against the runtime flags
The runtime flags must match the built enclave artifacts. Check:SGX_DEBUGmatches how the enclaves were builtSGX_PRERELEASEmatches the build and runtime expectations- the operator and KYC identity paths can both run with the current SGX flag combination
5. Verify where the failure occurs
Use the failing stage to choose the next diagnosis:| Failing stage | Most likely next focus |
|---|---|
| identity | SGX device access or debug-flag mismatch |
| acquire registration report | attestation mode, PCCS/AESM reachability, or custodian/report environment mismatch |
| registration-dependent startup | report parsing, registration sequencing, or operator-readiness dependency chain |
6. Verify the registration-side inputs
If the issue appears after identity succeeds, recheck the registration-side assumptions:- the report contains the required registration claims
- the localnet flow still uses the expected custodian and signer environment
- registration is happening in the correct sequence before operator readiness is expected
7. Decide the next route
| If the problem is… | Use this next |
|---|---|
| fixed mode, URL, or readiness facts | Node Operations Reference |
| a wider environment-readiness problem | How to Verify Operator Localnet Readiness |
| a private runbook or host-remediation task | Support Channels |