Troubleshooting

Common issues and solutions when developing mobile backends with Mizu.

Device Detection Issues

Device is nil

Problem: DeviceFromCtx(c) returns nil. Cause: Mobile middleware not applied. Solution:

app.Use(mobile.New())  // Must be added before routes

Wrong Platform Detected

Problem: Platform is unknown or incorrect. Cause: Missing headers or User-Agent not recognized. Solution:

Ensure client sends X-Platform header
Check User-Agent format
Enable User-Agent parsing: SkipUserAgent: false

app.Use(mobile.WithOptions(mobile.Options{
    SkipUserAgent: false,  // Parse User-Agent
}))

Version Middleware Issues

Version Always Default

Problem: VersionFromCtx(c) always returns default version. Cause: Client not sending version header. Solution:

// Check header name matches
app.Use(mobile.VersionMiddleware(mobile.VersionOptions{
    Header: "X-API-Version",  // Must match client
}))

Client should send:

X-API-Version: v2

Unsupported Version Error

Problem: 400 error for valid version. Cause: Version not in Supported list. Solution:

app.Use(mobile.VersionMiddleware(mobile.VersionOptions{
    Supported: []mobile.Version{
        {3, 0},
        {2, 0},  // Add missing version
    },
}))

Push Notification Issues

Invalid Token Format

Problem: Token validation fails. Cause: Token format doesn’t match provider. Solution:

// Check token format
if device.Platform == mobile.PlatformIOS {
    // APNS: 64 hex characters
    if !mobile.ValidateAPNS(token.Token) {
        // Invalid APNS token
    }
} else {
    // FCM: 140-200 alphanumeric characters
    if !mobile.ValidateFCM(token.Token) {
        // Invalid FCM token
    }
}

Provider Not Detected

Problem: PushProvider is empty. Cause: Platform not set or unknown. Solution:

// Explicitly set provider
registration := mobile.PushRegistration{
    Token:    token,
    Provider: mobile.PushFCM,  // Explicit provider
}

Deep Link Issues

AASA Not Served

Problem: /.well-known/apple-app-site-association returns 404. Cause: Middleware not configured or path conflict. Solution:

// Ensure middleware is added
app.Use(mobile.UniversalLinkMiddleware(mobile.UniversalLinkConfig{
    Apple: []mobile.AppleAppConfig{
        {TeamID: "...", BundleID: "..."},
    },
}))

App Not Opening from Link

Problem: Links open in browser instead of app. Causes:

AASA not accessible over HTTPS
Invalid AASA format
App not installed

Solution:

Verify AASA is served: curl https://yourdomain.com/.well-known/apple-app-site-association
Validate format: Apple Validation Tool
Check app entitlements

Sync Issues

Token Always Empty

Problem: req.Token is always empty. Cause: Token not sent in correct location. Solution:

// Check both header and query param
req := mobile.ParseSyncRequest(c)
// Looks for:
// - Header: X-Sync-Token
// - Query: ?sync_token=xxx

Client should send:

X-Sync-Token: YWJjMTIz...

Or:

GET /api/sync?sync_token=YWJjMTIz...

Full Sync Every Time

Problem: Always getting full sync instead of delta. Cause: Token not stored or sent incorrectly. Solution:

Store token after each sync
Send token on next request
Check full_sync query param not set

Error Response Issues

Error Format Wrong

Problem: Error response not matching expected format. Cause: Not using mobile.SendError. Solution:

// Use SendError for consistent format
return mobile.SendError(c, 400, mobile.NewError(
    mobile.ErrValidation,
    "Invalid request",
))

Trace ID Missing

Problem: Error responses don’t include trace ID. Solution:

err := mobile.NewError(mobile.ErrInternal, "Error").
    WithTraceID(c.Request().Header.Get("X-Request-ID"))

return mobile.SendError(c, 500, err)

Debug Logging

Add logging middleware to debug issues:

app.Use(func(next mizu.Handler) mizu.Handler {
    return func(c *mizu.Ctx) error {
        device := mobile.DeviceFromCtx(c)

        log.Debug("Request",
            "path", c.Path(),
            "platform", device.Platform,
            "app_version", device.AppVersion,
            "device_id", device.DeviceID,
            "api_version", c.Request().Header.Get("X-API-Version"),
        )

        return next(c)
    }
})

Testing Endpoints

Test with curl

# Test device detection
curl -H "X-Device-ID: test-123" \
     -H "X-App-Version: 2.0.0" \
     -H "X-Platform: ios" \
     http://localhost:3000/api/test

# Test versioning
curl -H "X-API-Version: v2" \
     http://localhost:3000/api/users

# Test sync
curl -H "X-Sync-Token: abc123" \
     http://localhost:3000/api/sync

Simulate Mobile Request

# iOS User-Agent
curl -A "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15" \
     http://localhost:3000/api/test

# Android User-Agent
curl -A "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36" \
     http://localhost:3000/api/test

Getting Started

Core Concepts

Backend Features

Native Platforms

Cross-Platform

Web & Games

Deployment

Templates

Reference

Device Detection Issues

Device is nil

Wrong Platform Detected

Version Middleware Issues

Version Always Default

Unsupported Version Error

Push Notification Issues

Invalid Token Format

Provider Not Detected

Deep Link Issues

AASA Not Served

App Not Opening from Link

Sync Issues

Token Always Empty

Full Sync Every Time

Error Response Issues

Error Format Wrong

Trace ID Missing

Debug Logging

Testing Endpoints

Test with curl

Simulate Mobile Request

Next Steps

Headers

API Reference

​Device Detection Issues

​Device is nil

​Wrong Platform Detected

​Version Middleware Issues

​Version Always Default

​Unsupported Version Error

​Push Notification Issues

​Invalid Token Format

​Provider Not Detected

​Deep Link Issues

​AASA Not Served

​App Not Opening from Link

​Sync Issues

​Token Always Empty

​Full Sync Every Time

​Error Response Issues

​Error Format Wrong

​Trace ID Missing

​Debug Logging

​Testing Endpoints

​Test with curl

​Simulate Mobile Request

​Next Steps

Headers

API Reference

Device Detection Issues

Device is nil

Wrong Platform Detected

Version Middleware Issues

Version Always Default

Unsupported Version Error

Push Notification Issues

Invalid Token Format

Provider Not Detected

Deep Link Issues

AASA Not Served

App Not Opening from Link

Sync Issues

Token Always Empty

Full Sync Every Time

Error Response Issues

Error Format Wrong

Trace ID Missing

Debug Logging

Testing Endpoints

Test with curl

Simulate Mobile Request

Next Steps