Saltar al contenido principal

Troubleshooting

Problemas habituales al gestionar DIDs en ISBE y sus soluciones.

Errores en el alta del DID​

400 Bad Request al llamar a insertFirstDidDocument​

Posibles causas:

  • proof no coincide con did + publicKey — Regenera la tripleta DID/PublicKey/Proof con ./did-gen did -p ... para asegurar coherencia.
  • vMethodId con formato incorrecto — Debe ser 32 bytes en base64url sin padding (43 caracteres exactos). El thumbprint JWK cumple este formato por defecto.
  • publicKey con prefijo equivocado — Para secp256k1, debe empezar por 0x04 (formato uncompressed).
  • modelDeploy del DID no coincide con la red — Si llamas a la API de PRO con un DID did:isbe:uc-pre:... la operación falla. Asegúrate de coincidencia entre los tres valores: red, DID y API.

La transacción se envía pero el DID no aparece​

  • Revisa el campo status del receipt. Si vale 0, la transacción se ejecutó pero el smart contract revirtió. Causas típicas:
    • La EOA from no tiene autorización para llamar a insertFirstDidDocument (esa operación tiene autorización especial).
    • El DID ya existe.
  • Si status es 1 pero el GET sigue devolviendo 404, espera unos segundos a que el indexador refleje el nuevo bloque.

Errores al firmar​

cli-tx-save lanza error de JSON al pasarle el cuerpo​

Si usas el binario interno cli-tx-save, el parámetro -t espera una cadena JSON entre comillas simples. Si el JSON contiene comillas dobles internas y lo pasas entre dobles, se rompe. Solución:

./sign-tx sign -p 0x<KEY> -t '{"to":"0x...","data":"0x..."}'

Si te sigue dando problemas, la alternativa más portable es firmar con ethers.js o eth_account directamente (ver Registro desde la API — paso 4).

ethers.js lanza "from must be undefined or match the signer"​

Los endpoints POST /contract/... devuelven from dentro del objeto. ethers se niega a serializar una transacción con from distinto al signer. Solución: descártalo antes de construir la Transaction:

const tx = Transaction.from({ ...raw, from: undefined });

eth_account se queja de campos en hexadecimal​

A diferencia de ethers, eth_account espera enteros nativos en gas, gasPrice, nonce, value y chainId. Convierte los hex 0x... con int(x, 16) antes de firmar.

La transacción firmada se rechaza con nonce too low​

El nonce devuelto por la API es el actual de la EOA. Si entre que generaste la transacción y la firmaste enviaste otra, el nonce puede haber quedado obsoleto. Solución: vuelve a llamar al endpoint para regenerar la transacción.

Errores al añadir verification methods​

La clave no aparece como assertionMethod​

Recuerda que la API expone los pasos por separado:

  1. addVerificationMethod registra la clave.
  2. addVerificationRelationship la asocia al uso (assertionMethod, authentication, etc.).

Si solo ejecutas el primero, la clave existe pero no es utilizable para firmar credenciales.

publicKeyType y formato de publicKey desalineados​

publicKeyType determina el formato del campo publicKey, no la curva. La curva sale del propio material:

  • publicKeyType: "secp256k1" → publicKey debe ser 64 bytes XY hexadecimales (formato uncompressed sin envoltura JWK). Si pegas aquí un JWK serializado, la API responde con 400 por formato inválido.
  • publicKeyType: "JsonWebKey2020" → publicKey debe ser un JWK válido serializado a JSON y codificado en hex. La curva real se lee del campo crv dentro del JWK. Acepta secp256k1, P-256, etc.

Errores frecuentes:

  • publicKeyType: "secp256k1" con un JWK serializado en publicKey → 400 BAD_REQUEST. Mete el JWK con publicKeyType: "JsonWebKey2020", o extrae los 64 bytes XY de la clave secp256k1 y envíalos como hex puro.
  • publicKeyType: "P-256" literal → 400 UNSUPPORTED con mensaje "The 'P-256' publicKeyType is temporarily unsupported." El valor está reservado en la spec pero deshabilitado en la implementación actual; usa JsonWebKey2020 con crv: "P-256" en su lugar.
  • publicKeyType: "JsonWebKey2020" con un JWK cuyo crv no esté soportado por el contrato → la inserción puede pasar la validación de formato pero la clave no será operativa para firmar. Las curvas comprobadas como funcionales son secp256k1 y P-256.

Confusión con la EOA from​

from siempre debe ser la EOA de la clave secp256k1 de control del DID, no la EOA derivada de la nueva clave P-256. La P-256 sirve para firmar off-chain; las transacciones on-chain las firma la secp256k1.

Errores al resolver​

404 Not Found​

  • El DID no está registrado en ese entorno (revisa el modelDeploy).
  • El DID está URL-encoded incorrectamente. Algunos clientes HTTP requieren codificar los : del DID. Prueba con cURL primero para descartar.

406 Not Acceptable​

El header Accept no es uno de los soportados:

  • application/did+ld+json
  • application/did+json

Errores de fondos / gas​

insufficient funds for gas​

La EOA no tiene saldo. En PRE puedes solicitar fondos en la sección Faucet del portal. En PRO los fondos se asignan en el onboarding inicial; contacta con ISBE si necesitas más.

gas required exceeds allowance​

El gasLimit devuelto por la API debería ser suficiente. Si te ocurre este error, no modifiques el gasLimit manualmente: vuelve a generar la transacción para que la API recalcule.

Errores en la cadena de confianza​

El CLI dice que la acreditación es inválida​

Causas frecuentes:

  • accreditedFor y accreditedSchemas no tienen la misma cardinalidad. Debe haber correlación 1:1.
  • Los tipos / esquemas no son subconjunto de los acreditados por la acreditación padre.
  • El domain no coincide con el de la acreditación padre.
  • La URL en accreditedBy no es accesible o devuelve un JWT inválido.

El verificador no encuentra mi acreditación​

  • Confirma con ISBE que la acreditación se ha publicado en el TIR.
  • Verifica que el verificador apunta al TIR del entorno correcto.

Pedir ayuda​

Si tras revisar estos puntos sigues teniendo problemas, abre una incidencia en el portal de soporte de ISBE adjuntando:

  • Entorno (PRE / PRO).
  • DID afectado.
  • Endpoint y cuerpo de la petición.
  • Respuesta completa (incluido tx_hash si la transacción llegó a enviarse).
  • Logs del CLI si la incidencia es local.