Troubleshooting Guide

This guide helps you resolve common issues encountered when working with the Shopify Vue App template.

Environment & Compatibility Requirements

Node.js Version Compatibility

The Shopify Vue App template requires:

• Node.js version 18.0.0 or higher
• npm version 9.0.0 or higher (comes with Node.js 18+)

If you're experiencing unexplained errors, first check your Node.js version:

node -v

If your version is below 18.0.0, upgrade Node.js using one of these methods:

• Using nvm (recommended):

  nvm install 18
  nvm use 18

• Direct download: https://nodejs.org/

Shopify CLI Requirements

The template depends on the Shopify CLI, which is automatically installed as a dependency. If you encounter CLI-related errors:

# Ensure the CLI is installed properly
npm install -g @shopify/cli
npm install -g @shopify/app

Common Errors and Solutions

Authentication Issues

"Not authorized" on app installation

Symptoms: App fails to install or shows authentication errors in the browser console.

Causes & Solutions:

1. Mismatched redirect URLs:

   • Check your shopify.app.toml file's redirect_urls section
   • Ensure it includes all necessary callback URLs (including /api/auth/callback)
   • Reset development environment: npm run dev:reset

2. Incorrect API credentials:

   • Verify your Shopify API key and secret are correct
   • Make sure the app is properly registered in the Partner Dashboard

3. HMAC validation failing:

   // Check your webhook-utils.js implementation
   const generatedHash = crypto
     .createHmac('SHA256', process.env.SHOPIFY_API_SECRET)
     .update(req.body, 'utf8')
     .digest('base64')

Webhook Issues

Webhooks not triggering or 401 errors

Symptoms: Webhooks aren't received or fail with a 401 Unauthorized error.

Solutions:

1. Check webhook registration:

   # List registered webhooks
   npm run shopify webhook list
   
   # Trigger a test webhook
   npm run dev:webhook

2. Validate webhook handler:

   • Ensure your processWebhook function is correctly implemented
   • Check that your validation middleware works properly
   • Add more detailed logging to diagnose issues

3. Webhook URL accessibility:

   • Make sure your development URL is publicly accessible
   • If using localhost, use ngrok or the Shopify CLI's tunnel

Database and Model Issues

"Failed to create user record" or similar errors

Symptoms: Database operations failing, user creation errors.

Solutions:

1. Check database initialization:

   # Remove existing development database to start fresh
   rm -f <path-to-your-app>/.env/dev.sqlite

2. Verify model implementation:

   • Ensure your User and Webhook models are properly implemented
   • Check for SQL syntax errors in your model queries
   • Confirm foreign key relationships are correct

3. Try with a production database:

   • For persistent issues, try configuring a MySQL or PostgreSQL database
   • Follow the instructions in the README for database configuration

Frontend Issues

App Bridge or Authentication Errors

Symptoms: "Failed to fetch" errors in console, app bridge not connecting.

Solutions:

1. Check App Bridge implementation:
   • Verify that you're using App Bridge correctly
   • Ensure the API key is properly passed to the app
2. Fix CORS issues:
   • Ensure your backend properly handles CORS headers
   • Check the proxy configuration in vite.config.js

Internationalization (i18n) Issues

Symptoms: Missing translations, app displaying only in English.

Solutions:

1. Verify locale loading:
   • Check that your language files are properly structured
   • Ensure the i18n plugin is properly initialized
   • Add debugging to see which locale is being loaded

Deployment Issues

App works locally but fails after deployment

Symptoms: App works in development but fails after deployment.

Solutions:

1. Environment variables:

   • Make sure all required environment variables are set in your hosting environment
   • Use npm run show:env to check required variables

2. Database configuration:

   • Ensure you've configured a production-ready database (not SQLite)
   • Check database connection strings and credentials

3. Build issues:

   • Verify that the build process completes successfully
   • Check for platform-specific path issues (Windows vs. Unix)

Debugging Tips

Enable Verbose Logging

Add more detailed logging to help diagnose issues:

// In your server code
console.log('Detailed request info:', {
  headers: req.headers,
  query: req.query,
  body: typeof req.body === 'string' ? 'String body - not logging' : req.body,
  shop: req.query.shop
})

Inspect Network Requests

Use the browser's developer tools to inspect network requests:

1. Open the browser's Developer Tools (F12)
2. Go to the Network tab
3. Filter for requests to your API endpoints
4. Check for status codes, headers, and response data

Testing Webhooks Locally

# Trigger a specific webhook type
npm run dev:webhook
# When prompted, choose the webhook type and provide the webhook URL
# Use <app-url>/api/webhooks as the endpoint

Getting Help

If you continue experiencing issues:

1. Check the GitHub repository issues
2. Create a new issue with detailed information about your problem
3. Include your Node.js version, operating system, and steps to reproduce the issue