Docs Using the wallet Troubleshooting

Troubleshooting

Authentication and Login Issues

Cannot Log In

Problem: Login button doesn’t work or redirect fails

Solutions:

  1. Check your browser
    • Try a different browser (Chrome, Firefox, Edge)
    • Clear browser cache and cookies
    • Disable browser extensions temporarily
    • Allow popups for the wallet domain
  2. Verify your credentials
    • Confirm username/email is correct
    • Check password in your identity provider
    • Verify your account is active
    • Contact identity provider admin if locked out
  3. Check system access
    • Confirm you’re in the company users list
    • Verify OAuth/OIDC is configured
    • Contact your system administrator

Session Expires Quickly

Problem: You’re logged out frequently

Cause: Session timeout settings

Solutions:

  • Contact administrator about session duration
  • Save work frequently
  • Keep the browser tab active
  • Refresh page periodically

“Unauthorized” or “Forbidden” Errors

Problem: Error messages when trying to perform actions

Cause: Insufficient permissions for your role

Common permission requirements:

  • Creating a DID requires CREATE_DID. Creating or importing a key requires CREATE_KEY
  • Starting a key export requires EXPORT_KEY. Starting a key deletion requires DELETE_KEY. Controllers who only approve do not need those permissions
  • Issuing credentials requires CREATE_CREDENTIAL + SIGN_CREDENTIAL
  • Revoking credentials requires UPDATE_CREDENTIAL
  • Editing company settings requires UPDATE_COMPANY

Solutions:

  1. Check your current role
    • Open the account menu and choose Profile
    • See what permissions your role grants
    • Compare that list with Roles and permissions
  2. Verify the operation matches your role
    • AUDITOR: Read-only, cannot perform changes
    • CREDENTIAL_MANAGER: Can revoke, suspend, and co-sign. Creating a credential also needs CREATE_CREDENTIAL
    • KEY_OPERATOR: Can sign and update keys. The credentials screen also needs READ_CREDENTIAL
    • COMPANY_ADMIN: Full access within your company
    • ADMIN: Full access to all companies
  3. Contact your administrator
    • Explain what you’re trying to do
    • Request role change if justified
    • May need promotion to higher role
  4. Verify you’re in the correct company context
    • Some operations are company-specific
    • Check you’re working on your assigned company

DID Management Issues

Cannot Create did:web

Problem: Error when creating did:web identifier

Common causes and solutions:

  1. “No domains configured”
    • Your company needs at least one domain
    • Open the account menu, choose Company Settings, and add the domain
    • Or ask a COMPANY_ADMIN to add it
  2. “Domain validation failed”
    • Use a domain such as example.com or example.com/issuer (no https://)
    • Check for typos
    • The dialog strips a pasted https:// prefix and shows the resulting DID before you save
  3. “DID already exists”
    • That did:web is already in the wallet
    • Choose a different domain or path
    • Search Identities for the existing one

DID Resolution Fails

Problem: DID shows warning icon, doesn’t resolve

For did:web:

Possible causes:

  • Domain DNS not configured
  • DID Document not published at correct location
  • Network connectivity issues
  • HTTPS certificate problems

Solutions:

  1. Check DID in browser: https://your-domain.com/.well-known/did.json
  2. Contact system administrator if not accessible
  3. Verify domain ownership
  4. Check DNS configuration

For did:key:

  • Did:key should resolve automatically
  • If it fails, try deleting and recreating
  • Contact administrator if problem persists

Cannot Add Key to DID

Problem: Error when trying to add verification method

Solutions:

  1. Check DID exists: Verify DID in your list
  2. Verify permissions: Confirm you can manage this DID
  3. Check key purpose: Ensure purpose is valid
  4. Try different key type: Ed25519 vs ES256
  5. Review audit log: Check for error details

Key Management Issues

Lost User Secret Key File

Problem: Cannot find user secret key file for a key

Solutions:

If you are the only person in the group:

  • The key file cannot be recreated
  • Deleting the key needs that same key file, so the key stays until a controller who can still provide a secret approves the deletion
  • If you still have an exported copy and its passphrase, import it onto the identity as a new key
  • Otherwise add a new key on the identity and use that key from now on
  • Credentials already signed with the old key can still be checked, because the public key stays in the DID document until the key is deleted

If other people share your controller group:

  • They can still use the key, and they can approve an export or a deletion
  • You can remove your own access with Delete Personal Access after someone else is in the group
  • Ask them to add you again only if you have a new key file to enroll

Prefer more than one person in a group, or more than one group, before a key is used for important credentials.

Prevention:

  • Store key files in password manager with file storage
  • Keep backup copies in secure locations
  • Document where key files are stored
  • Use encrypted storage for key files

Key File Upload Fails

Problem: Error when uploading key file during verification

Solutions:

  1. Verify correct file
    • Must be the EXACT file just downloaded
    • Cannot recreate or edit the file
    • File hash must match
  2. File corruption
    • Download may have failed
    • Try starting key creation over
    • Check file size (should be consistent)
  3. Browser issues
    • Try different browser
    • Clear cache and retry
    • Check file upload permissions

Cannot Sign with Key

Problem: Signing fails when trying to issue credential

Common causes:

  1. Wrong user secret key file
    • Double-check you’re uploading correct key file
    • Verify this key file is for THIS key
    • Ensure file hasn’t been corrupted
  2. Several controller groups
    • One person from each group must provide a secret
    • Open the bell in the header to see whether the request is still waiting
    • Contact someone in each group that has not approved
  3. Key not found
    • Verify key still exists
    • Check DID has this key
    • Refresh key list

Pending Request Not Appearing

Problem: Expected pending request doesn’t show up

Solutions:

  1. Check correct view
    • Open the bell in the header
    • Refresh the page
  2. Verify you’re a controller
    • Confirm you’re listed as controller on the key
    • Check request is for a key you control
    • Verify email matches your account
  3. Request already processed
    • Check audit log for completion
    • Another controller may have cancelled
    • Operation may have completed

Credential Issuance Issues

Cannot Issue Credential

Problem: Error when trying to create credential

Solutions:

  1. “No DIDs available”
    • Create a DID first
    • Go to Identities and click Add identity or Add default
  2. “No keys available”
    • Add key to your DID
    • Ensure key purpose includes “Assertion”
  3. “Invalid subject ID”
    • Subject must be valid IRI format
    • Examples: did:web:example.com, https://example.com/id/123
    • Cannot be blank
  4. “Signing failed”
    • Verify user secret is correct
    • Check key still exists
    • Review pending requests for multi-controller keys

Credential Not Appearing in List

Problem: Issued credential doesn’t show up

Solutions:

  1. Refresh the page: Credential list may need reload
  2. Check filters: Clear any search filters
  3. Verify issuance succeeded: Check for error message
  4. Review audit log: Confirm credential was created
  5. Database delay: Wait 30 seconds and refresh

Cannot Revoke Credential

Problem: Revocation fails or option not available

Solutions:

  1. “Revocation not enabled”
    • Credential was created without revocation support
    • Cannot revoke after issuance
    • Must reissue with revocation enabled
  2. Already revoked
    • Check credential status
    • Cannot revoke twice
  3. Permissions issue
    • Verify you have rights to revoke
    • Must be controller of the issuance key

Verification Fails

Problem: Credential doesn’t verify correctly

Check these:

  1. Signature validity
    • DID must still exist
    • Key must still be in DID Document
    • Check DID resolution works
  2. Status issues
    • Is credential revoked?
    • Is credential suspended?
    • Check status list is accessible
  3. Expiration
    • Has credential expired?
    • Check expiration date
  4. Network issues
    • Can verifier reach your wallet?
    • Is public registry accessible?
    • Test with curl or browser

GS1-Specific Issues

Cannot Issue GS1 License

Problem: Error when issuing GS1 prefix or company license

Solutions:

  1. Company prefix does not extend the selected license
    • Select the prefix license this company prefix extends
    • The company prefix must start with that license value
    • It must also be longer. Example: base 061414, company prefix 061414112345
  2. Claiming a license by number
    • A number must be 1 to 13 digits
    • A full address must be HTTPS and must be the license’s registry URL

GLN Validation Fails

Problem: Global Location Number rejected

Solution:

  • A GLN is 13 digits, including the check digit, with no spaces. Example: 0614141000017
  • A GS1 Digital Link is also accepted when it contains AI 414 and that GLN’s check digit is valid

Product GTIN Invalid

Problem: Product credential rejected due to GTIN error

Solutions:

  1. Check GTIN format
    • GTIN-8: 8 digits
    • GTIN-12: 12 digits (UPC)
    • GTIN-13: 13 digits (EAN)
    • GTIN-14: 14 digits
  2. Verify check digit
    • Last digit is calculated checksum
    • Use GS1 check digit calculator
    • Must be exactly correct
  3. Confirm company prefix
    • GTIN must start with your company prefix
    • Must have valid company prefix license

Error Messages

“Invalid Token” or “Token Expired”

Cause: Authentication session expired

Solution:

  1. Log out
  2. Log back in
  3. Retry operation

“Network Error” or “Cannot Connect”

Cause: Connectivity issues

Solutions: 1. Check internet connection 2. Verify wallet URL is correct 3. Test in different browser 4. Contact administrator if persistent

“Internal Server Error”

Cause: Backend issue

Solutions:

  1. Wait 1 minute and retry
  2. Check system status (ask administrator)
  3. Report error with timestamp
  4. Check audit log for details

Getting Help

Information to Provide

When contacting support, include:

  1. Your information
    • Email/username
    • Company name
    • Role in the system
  2. Problem description
    • What you were trying to do
    • Exact error message (screenshot)
    • When it happened (timestamp)
    • Steps to reproduce
  3. Context
    • Browser and version
    • Operating system
    • Did it ever work before?
    • Can others reproduce it?

Support Resources

Documentation:

  • This manual

Administrator contacts:

  • System administrator (provided by your organization)
  • Email: [mailto:sebastian.schmittner@eecc.de]
  • Support portal: [https://id.eecc.de]

Self-help:

  • Check audit log for details
  • Review recent operations
  • Test in different browser
  • Verify permissions

Escalation

When to escalate:

  • Security incidents
  • Data loss
  • Multiple users affected
  • System-wide issues
  • Suspected compromise

How to escalate:

  1. Contact administrator immediately
  2. Document the issue
  3. Stop using affected features
  4. Preserve evidence (screenshots, logs)
  5. Follow incident response procedures