Troubleshooting

This document provides solutions to common issues when deploying and using the Arculus FIDO2 Server.

Deployment Issues

Stack Creation Fails - VPC/Subnet Mismatch

Error:

All input subnets must be from the same VPC

Cause: Subnets specified in parameters belong to different VPCs.

Solution:

# Verify all subnets belong to the same VPC
aws ec2 describe-subnets --subnet-ids subnet-xxx,subnet-yyy \
  --query 'Subnets[].{SubnetId:SubnetId,VpcId:VpcId}' --output table

Certificate Validation Failed

Error:

Certificate ARN is invalid or not found

Cause: SSL certificate doesn't exist or is in the wrong region.

Solution:

# Verify certificate exists and is validated
aws acm list-certificates \
  --query 'CertificateSummaryList[?DomainName==`auth.example.com`]'

# Check certificate status
aws acm describe-certificate \
  --certificate-arn arn:aws:acm:us-east-1:123:certificate/xxx

Ensure certificate is in the same region as your deployment.

Container Image Pull Failed

Error:

CannotPullContainerError: pull image manifest has been retried

Cause: ECS cannot access the container registry.

Solution:

# Verify ECR repository exists
aws ecr describe-repositories

# Verify images are present
aws ecr list-images --repository-name pyfido

# Check ECS task execution role has ECR permissions

Ensure NAT Gateway is configured for private subnets to access ECR.

MongoDB Connection Issues

Cannot Connect to MongoDB

Error:

ServerSelectionTimeoutError: connection timed out

Cause: Network connectivity or authentication issues.

Solutions:

1. Check security groups:

   • MongoDB security group must allow inbound from ECS security group on port 27017

2. Verify connection string format:

   mongodb://username:password@host:27017/database

3. Test connection from container:

   docker exec pyfido python3 -c "from pymongo import MongoClient; c=MongoClient('$MONGOURL'); print(c.list_database_names())"

4. For Atlas: Ensure IP whitelist includes NAT Gateway IPs or use VPC Peering.

MongoDB Authentication Failed

Error:

Authentication failed: bad auth : Authentication failed

Cause: Invalid username or password.

Solution:

• Verify credentials in environment variables

• Check for special characters in password (URL-encode if needed)

• Confirm user has appropriate database permissions

Registration Issues

Session Expired (E0024R)

Error:

{"status": "failed", "errorMessage": "E0024R: Session expired", "statuscode": "408"}

Cause: Too much time elapsed between begin and complete calls.

Solutions:

1. Increase session timeout:

   docker run -e SESSION=120 pyfido:latest

2. Ensure cookies are properly maintained:

   fetch(url, { credentials: 'include' });

3. Check for network delays between client and server.

Unknown Relying Party (E0025R)

Error:

{"status": "failed", "errorMessage": "E0025R: Unknown relying party example.com"}

Cause: The domain is not registered in the tenant configuration.

Solutions:

1. Check available domains:

   curl https://fido.example.com/tenants

2. Add the domain to tenant configuration in MongoDB.

3. Use X-ArculusFido-RelyingParty header:

   curl -H "X-ArculusFido-RelyingParty: example.com" ...

Invalid Keypair JSON (E0023R)

Error:

{"status": "failed", "errorMessage": "E0023R: Invalid JSON due to keypair for deviceinfo"}

Cause: Malformed keypair object in registration request.

Solution:

Ensure keypair is a valid JSON object:

{
  "keypair": {
    "deviceinfo": "User's Device"
  }
}

If passing a string, it will be wrapped:

{
  "keypair": "device-id-string"
}

Authentication Issues

User Not Found (403)

Error:

{"status": "failed", "errorMessage": "No account for user"}

Cause: Username has no registered credentials.

Solutions:

1. Verify user has completed registration

2. Check for username case sensitivity

3. Confirm correct relying party/tenant

Signature Verification Failed

Error:

InvalidSignature: Signature did not match

Cause: Cryptographic verification failed.

Possible causes:

1. Credential mismatch: User is using a different authenticator

2. Counter regression: Possible cloned authenticator

3. Challenge mismatch: Session state corrupted

Solutions:

1. Have user re-register the authenticator

2. Check for session cookie issues

3. Review server logs for detailed error

Invalid Base64URL Encoding

Errors:

• E0006R: id is not base64url

• E0015R: id is not base64url

• E0018R: authenticatorData is not base64url

• E0020R: clientDataJSON is not base64url

Cause: Response data is not properly Base64URL encoded.

Solution:

Ensure proper encoding in client:

const base64url = btoa(String.fromCharCode(...new Uint8Array(buffer)))
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=/g, '');

Health Check Issues

Load Balancer Health Checks Failing

Symptoms:

• Tasks marked unhealthy

• Service not reaching desired count

Solutions:

1. Check security groups:

   # ALB must be able to reach tasks on health check port
   aws ec2 describe-security-groups --group-id sg-xxx

2. Verify application is listening:

   docker exec pyfido curl -s http://localhost:5001/health

3. Check health check configuration:

   • Path: /health

   • Port: 5001

   • Protocol: HTTP

   • Healthy threshold: 2

   • Interval: 30s

4. Review application logs:

   aws logs tail /ecs/arculus-auth/production/pyfido --follow

Performance Issues

High CPU Usage

Symptoms: Slow response times, high CPU metrics.

Solutions:

1. Increase CPU allocation in task definition

2. Add more task instances

3. Enable Fargate Spot for cost-effective scaling

4. Review signature verification load

High Memory Usage

Symptoms: OOM errors, task restarts.

Solutions:

1. Increase memory allocation

2. Check for memory leaks in logs

3. Review MongoDB query patterns

4. Enable garbage collection monitoring:

   docker run -e PYTHONUNBUFFERED=1 pyfido:latest

Slow Response Times

Symptoms: API latency > 500ms.

Solutions:

1. Check MongoDB query performance

2. Enable connection pooling

3. Review network latency to database

4. Consider adding Redis cache layer

5. Check if MDS verification is adding latency

SSL/TLS Issues

Certificate Not Trusted

Error: Browser shows certificate warning.

Cause: Certificate not properly configured or validated.

Solutions:

1. Verify certificate is issued and validated:

   aws acm describe-certificate --certificate-arn arn:aws:acm:...

2. Check DNS validation records are in place

3. Ensure certificate covers the correct domain

Mixed Content Errors

Error: Browser blocks insecure content.

Cause: Application makes HTTP requests from HTTPS page.

Solution:

Ensure all API calls use HTTPS:

const apiUrl = 'https://fido.example.com/fidoapi/...';

CORS Issues

CORS Error in Browser

Error:

Access to fetch has been blocked by CORS policy

Cause: Cross-origin request blocked.

Solutions:

1. Verify server CORS configuration allows your origin

2. Ensure credentials are included:

   fetch(url, { credentials: 'include' });

3. Check Access-Control-Allow-Origin header in response

4. Verify preflight OPTIONS request succeeds

Logging and Debugging

Enable Debug Logging

docker run -e LOGLEVEL=5 pyfido:latest

Log levels:

• 1: Errors only

• 2: Warnings

• 3: Info

• 4: Debug

• 5: Verbose

View CloudWatch Logs

# Tail logs
aws logs tail /ecs/arculus-auth/production/pyfido --follow

# Filter for errors
aws logs filter-log-events \
  --log-group-name /ecs/arculus-auth/production/pyfido \
  --filter-pattern "ERROR"

Container Debugging

# Interactive shell
docker exec -it pyfido /bin/bash

# Check running processes
docker exec pyfido ps aux

# Check network
docker exec pyfido netstat -tlnp

Error Code Reference

Registration Errors (E00xxR)

Code	Description
E0002R	Type not supplied
E0003R	Type not string
E0004R	Type not set to public-key
E0005R	id not supplied
E0006R	id is not base64url
E0007R	Signature is not base64url
E0008R	clientDataJSON is not base64url
E0009R	tokenBinding not supported
E0023R	Invalid keypair JSON
E0024R	Session expired
E0025R	Unknown relying party
E0026R	Invalid header format

Authentication Errors (E00xxR)

Code	Description
E0010R	response is not dict
E0011R	Type not supplied
E0012R	Type not string
E0013R	Type not set to public-key
E0014R	id not supplied
E0015R	id is not base64url
E0016R	authenticatorData missing
E0017R	authenticatorData missing
E0018R	authenticatorData is not base64url
E0019R	Signature is not base64url
E0020R	clientDataJSON is not base64url
E0021R	clientDataJSON missing
E0022R	tokenBinding not supported

Attestation Errors (E1xxxR)

Code	Description
E1000R	Invalid AAGUID length
E1001R	Wrong credential data length
E1002R	Wrong authenticator data length
E1003R	Invalid AAGUID for fido-u2f
E1004R	attStmt alg field missing
E1005R	attStmt alg is not type number
E1006R	attStmt sig field missing
E1007R	attStmt sig is not bytes
E1008R	attStmt sig is empty
E1009R	ALG does not match metadata

Common Mistakes

SDK Integration Mistakes

Mistake	Symptom	Fix
Not persisting session cookies	E0024R "Session expired" on every complete call	Store cookies from begin response; send with complete request
Wrong relying party ID	E0025R "Unknown relying party" or E2007R	RP ID must match server domain configuration exactly
Calling authenticate before register	403 "No account for user"	Complete registration flow first for new users
Using wrong PIN	608 "Get PIN Token Failed"	Verify PIN; after 3 failures card may lock
Card removed during operation	600 "Tag Lost"	Keep card on device until operation completes
Missing NFC permissions (Android)	615 "NFC Not Available"	Add <uses-permission android:name="android.permission.NFC"/>
Testing on simulator	Various NFC errors	NFC requires physical device; simulators don't support NFC

Server Configuration Mistakes

Mistake	Symptom	Fix
MongoDB not reachable	Connection timeout on startup	Check security groups allow port 27017 from ECS
Wrong domain parameter	Registration fails silently	Ensure --domain matches your actual domain
Session timeout too short	Frequent E0024R errors	Increase --session parameter (default 60s)
AAGUID whitelist enabled but empty	E1046R error	Add valid AAGUIDs or disable whitelist (--aaguid off)
Missing tenant configuration	E0025R for valid domains	Add --tenant parameters for each domain

Backend-Proxied Integration Mistakes

Mistake	Symptom	Fix
Not forwarding session cookies	E0024R between phases	Backend must store and forward cookies from FIDO2 server
Modifying challenge data	E2006R "Wrong challenge"	Pass challenge exactly as received from FIDO2 server
Wrong origin in clientDataJSON	E2005R "Invalid origin"	Origin must match FIDO2 server's expected origin
Calling complete without begin	E0027R "Session expired"	Always call begin endpoint before complete
Reusing sessions	Intermittent failures	Each registration/auth needs a fresh begin call

Mobile App Mistakes

Mistake	Symptom	Fix
Not destroying ArculusFidoAsync	Memory leaks	Call ArculusFidoAsync.destroyInstance() in onDestroy()
Blocking UI thread	App freezes during card ops	All SDK calls should be on background thread
Not handling all callbacks	Missing error feedback	Implement all ArculusFidoResultCallback methods
Hardcoded test server	Works in dev, fails in prod	Use configuration for server URLs

Debugging Tips

1. Enable verbose logging: --loglevel 5 shows detailed request/response data

2. Test API directly: Use curl to isolate SDK vs server issues

3. Check session state: /fidoapi/test confirms API is accessible

4. Verify MongoDB: /fidoapi/testmongo confirms database connectivity

5. Review timestamps: E0024R often means clock skew between client/server

Getting Help

If issues persist:

1. Collect logs with debug level enabled

2. Document reproduction steps

3. Note environment details (cloud, region, versions)

4. Contact Arculus support with collected information