Troubleshooting

Solutions for common issues with Norrix CLI, SDK, and builds.

Authentication Issues

”Unauthorized” Errors

Symptoms:

• CLI commands fail with “Unauthorized”
• API returns 401 status

Solutions:

1. Check if you’re signed in:

   norrix whoami

2. Re-authenticate:

   norrix sign-out
   norrix sign-in

3. Verify organization:

   norrix orgs current

4. Check environment (prod vs dev):

   norrix whoami        # Production
   norrix --dev whoami  # Development

API Key Issues

Symptoms:

• CI/CD builds fail with auth errors
• “Invalid or expired API key”

Solutions:

1. Verify key hasn’t expired:

   • Dashboard → Settings → API Keys
   • Check expiration date

2. Verify key has required scopes:

   • build for build operations
   • submit for submissions
   • update for OTA updates

3. Check key is for correct environment:

   • Production keys only work with norrix.net
   • Dev keys only work with dev.norrix.dev

4. Ensure key is set correctly:

   echo $NORRIX_API_KEY  # Should show key value

Token Refresh Failed

Symptoms:

• “Failed to refresh token”
• Prompted to sign in frequently

Solutions:

1. Clear cached tokens:

   rm -rf ~/.norrix
   norrix sign-in

2. Check system time is correct (affects token validation)

Build Failures

Build Fails Immediately

Symptoms:

• Build status shows “failed” within seconds
• No build logs generated

Solutions:

1. Run with verbose mode:

   norrix build ios release --verbose

2. Check project builds locally first:

   ns build ios --release

3. Verify signing credentials exist and are valid

4. Check entitlements:

   • May have hit monthly limit on Free tier
   • Dashboard → Settings → Usage

iOS Code Signing Errors

Symptoms:

• “Code signing failed”
• “No matching provisioning profile”
• Certificate errors

Solutions:

1. Verify Team ID:

   # Should be 10 alphanumeric characters
   norrix build ios release --team-id ABC123XYZ0

2. Check certificate expiration:

   • Apple Developer Portal → Certificates
   • Regenerate if expired

3. Verify provisioning profile:

   • Matches bundle ID
   • Includes correct certificate
   • Not expired

4. For ASC API issues:

   • Verify Key ID and Issuer ID
   • Confirm .p8 file is unmodified
   • Check API Key has Admin access

Android Signing Errors

Symptoms:

• “Keystore was tampered with”
• “Alias not found”
• Password errors

Solutions:

1. Verify keystore path:

   ls -la ./path/to/keystore.jks

2. Test keystore locally:

   keytool -list -v -keystore ./path/to/keystore.jks

3. Verify key alias exists in keystore

4. Check passwords are correct (no trailing whitespace)

Build Number Conflicts

Symptoms:

• “Build number already exists”
• App Store rejection for duplicate build

Solutions:

1. Use explicit build number:

   norrix build ios release --build-number 50

2. Check existing builds in dashboard

3. Build numbers must always increase for App Store

OTA Update Issues

Update Not Detected

Symptoms:

• App shows no updates available
• checkForUpdates() returns updateAvailable: false

Solutions:

1. Verify SDK initialization runs early:

   // Should be in app.ts or main.ts, before app starts
   import { initNorrix } from '@norrix/client-sdk';
    
   initNorrix({
     updateUrl: 'https://norrix.net',
     checkForUpdatesOnLaunch: true,
   });

2. Check updateUrl is correct:

   • Production: https://norrix.net
   • Development: https://dev.norrix.dev

3. Verify update version is higher:

   • Check currentVersion vs update version
   • Must be semver greater

4. Check bundle ID matches:

   • App bundle ID must match published update

5. Verify update was published successfully:

   • Dashboard → Updates → Check status

Update Incompatible

Symptoms:

• requiresStoreUpdate: true
• “Native changes detected”

Solutions:

1. Check fingerprints:

   norrix fingerprint compare --from <buildId>

2. Review what changed:

   • Plugin version updates?
   • App_Resources changes?
   • NativeSource modifications?

3. If changes are intentional:

   • Publish a new store build
   • Then resume OTA updates

Update Doesn’t Apply

Symptoms:

• Update downloads but app doesn’t change
• Same version after restart

Solutions:

1. Updates apply on app restart:

   • Use promptToRestartAfterInstall: true
   • Or call norrix.applyUpdate(true) to force close

2. Check status callback:

   statusCallback: (status, data) => {
     console.log('Status:', status, data);
   };

3. Verify update was installed:

   • Status should reach UPDATE_INSTALLED
   • Check for ERROR status

4. Check for HMR interference:

   • Disable HMR in production builds
   • SDK skips updates when HMR is active

Update Download Fails

Symptoms:

• ERROR status with download message
• Partial download

Solutions:

1. Check network connectivity

2. Verify URL hasn’t expired:

   • URLs valid for 1 hour
   • Retry check to get fresh URL

3. Check device storage:

   • Sufficient space for update bundle

Nx Workspace Issues

Project Not Found

Symptoms:

• “No NativeScript projects found”
• “Project ‘x’ not found”

Solutions:

1. Ensure you’re in workspace root:

   ls nx.json  # Should exist

2. Check project has nativescript.config.ts:

   ls apps/my-app/nativescript.config.ts

3. Verify project.json exists with correct name:

   {
     "name": "my-app"
   }

4. Use --project flag:

   norrix build ios release --project my-app

Dependencies Missing

Symptoms:

• Build fails with import errors
• “Cannot find module ‘@myorg/shared’”

Solutions:

1. Run with verbose:

   norrix build ios release --project myapp --verbose

2. Check tsconfig.base.json paths:

   {
     "compilerOptions": {
       "paths": {
         "@myorg/shared": ["libs/shared/src/index.ts"]
       }
     }
   }

3. Verify libs are in Nx dependency graph:

   npx nx graph

4. Check for implicit dependencies in project.json

Path Alias Issues

Symptoms:

• “Module not found: @myorg/utils”
• Works locally but fails in cloud

Solutions:

1. Ensure paths use correct format:

   {
     "paths": {
       "@myorg/utils": ["libs/utils/src/index.ts"]
     }
   }

2. Check webpack aliases match tsconfig paths

3. Verify all path targets exist

Environment Variable Issues

Variable Not Injected

Symptoms:

• Build doesn’t have expected env var
• process.env.MY_VAR is undefined

Solutions:

1. Verify variable is set:

   norrix env list

2. Check project scope:

   norrix env list --project my-app

3. Ensure variable is declared in config:

   // norrix.config.ts
   env: {
     variables: ['MY_VAR'],
   }

4. Check subscription:

   • Env variables require Pro tier

Secret Value Incorrect

Symptoms:

• Build uses wrong secret value
• API calls fail with auth errors

Solutions:

1. Re-set the variable:

   norrix env set MY_SECRET "correct_value"

2. Verify visibility is correct:

   norrix env list  # Shows visibility type

Getting Help

Information to Gather

When contacting support, include:

1. Build/Submit/Update ID
2. CLI version: norrix --version
3. Error message (full text)
4. Verbose output: --verbose
5. Platform and configuration

Support Channels

• Free tier: Community forums
• Pro tier: Email support
• Enterprise tier: Priority support

Useful Commands

# Version info
norrix --version
 
# Current auth status
norrix whoami
 
# Current organization
norrix orgs current
 
# Verbose build
norrix build ios release --verbose
 
# Check fingerprint
norrix fingerprint ios
 
# Compare with build
norrix fingerprint compare --from <buildId>