@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/docs/troubleshooting/common-errors.md

@@ -0,0 +1,758 @@
+# Common Errors and Solutions
+
+## Overview
+
+This document catalogs frequently encountered errors in cross-platform Dynamics 365 development and
+provides step-by-step solutions for both Windows and Mac environments.
+
+## Table of Contents
+
+1. [Build and Compilation Errors](#build-and-compilation-errors)
+2. [Deployment Errors](#deployment-errors)
+3. [Authentication Errors](#authentication-errors)
+4. [Environment Setup Errors](#environment-setup-errors)
+5. [Git and Version Control Errors](#git-and-version-control-errors)
+6. [Package Management Errors](#package-management-errors)
+7. [Runtime Errors](#runtime-errors)
+
+## Build and Compilation Errors
+
+### Error: TypeScript compilation failed
+
+**Symptoms:**
+
+```
+error TS2307: Cannot find module './MyComponent' or its type declarations.
+error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
+```
+
+**Cause:** TypeScript configuration issues or incorrect import paths
+
+**Solution:**
+
+**Step 1: Check TypeScript configuration**
+
+```bash
+# Validate tsconfig.json
+npx tsc --showConfig
+
+# Check for TypeScript errors
+npm run typecheck
+```
+
+**Step 2: Fix common import issues**
+
+```typescript
+// ❌ Wrong - case mismatch
+import MyComponent from './mycomponent';
+
+// ✅ Correct - exact case match
+import MyComponent from './MyComponent';
+
+// ❌ Wrong - missing extension in some configs
+import utils from './utils';
+
+// ✅ Correct - explicit extension
+import utils from './utils.ts';
+```
+
+**Step 3: Platform-specific path resolution**
+
+```json
+// tsconfig.json - ensure cross-platform compatibility
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@components/*": ["src/components/*"]
+    },
+    "moduleResolution": "node"
+  }
+}
+```
+
+### Error: Webpack build fails with "Module not found"
+
+**Symptoms:**
+
+```
+Module not found: Error: Can't resolve './component' in '/project/src'
+```
+
+**Cause:** Incorrect file paths or case sensitivity issues
+
+**Solution:**
+
+**Windows:**
+
+```powershell
+# Check file existence (case-insensitive)
+Test-Path "src\components\MyComponent.tsx"
+
+# List actual file names
+Get-ChildItem "src\components" | Select-Object Name
+```
+
+**Mac:**
+
+```bash
+# Check file existence (case-sensitive)
+ls -la src/components/MyComponent.tsx
+
+# Find files with case variations
+find src/components -iname "*mycomponent*"
+```
+
+**Cross-platform fix:**
+
+```javascript
+// webpack.config.js - Add case-sensitive resolver
+module.exports = {
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+    },
+    extensions: ['.tsx', '.ts', '.js', '.jsx'],
+    // Enforce case sensitivity
+    plugins: [new CaseSensitivePathsPlugin()],
+  },
+};
+```
+
+## Deployment Errors
+
+### Error: PowerShell execution policy prevents script execution
+
+**Symptoms:**
+
+```
+.\deploy.ps1 : File cannot be loaded because running scripts is disabled on this system.
+At line:1 char:1
++ .\deploy.ps1
++ ~~~~~~~~~~~~
+    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
+    + FullyQualifiedErrorId : UnauthorizedAccess
+```
+
+**Cause:** Windows PowerShell execution policy is set to Restricted
+
+**Solution:**
+
+**Step 1: Check current policy**
+
+```powershell
+Get-ExecutionPolicy -List
+```
+
+**Step 2: Set appropriate policy**
+
+```powershell
+# For current user (recommended)
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# For current session only
+Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
+
+# Verify change
+Get-ExecutionPolicy
+```
+
+**Step 3: Alternative using bypass**
+
+```powershell
+# Run script with bypass
+powershell -ExecutionPolicy Bypass -File .\deploy.ps1 -Environment dev
+```
+
+### Error: Bash script permission denied
+
+**Symptoms:**
+
+```bash
+bash: ./deploy.sh: Permission denied
+```
+
+**Cause:** Script doesn't have execute permissions
+
+**Solution:**
+
+**Step 1: Check current permissions**
+
+```bash
+ls -la deployment/scripts/deploy.sh
+```
+
+**Step 2: Add execute permission**
+
+```bash
+# Single script
+chmod +x deployment/scripts/deploy.sh
+
+# All shell scripts
+chmod +x deployment/scripts/*.sh
+
+# Recursive for all scripts
+find deployment -name "*.sh" -exec chmod +x {} \;
+```
+
+**Step 3: Commit permission changes**
+
+```bash
+git update-index --chmod=+x deployment/scripts/deploy.sh
+git commit -m "fix: make deployment scripts executable"
+```
+
+### Error: Dynamics 365 connection failed
+
+**Symptoms:**
+
+```
+Error: Unable to connect to Dynamics 365 environment
+HTTP 401: Unauthorized
+```
+
+**Cause:** Authentication credentials or configuration issues
+
+**Solution:**
+
+**Step 1: Verify environment configuration**
+
+```bash
+# Check configuration file exists
+ls -la config/environments/dev.json
+
+# Validate JSON syntax
+jq empty config/environments/dev.json
+```
+
+**Step 2: Test authentication**
+
+**Windows:**
+
+```powershell
+# Test connection script
+.\deployment\scripts\test-connection.ps1 -Environment dev -Verbose
+
+# Check environment variables
+Get-ChildItem Env: | Where-Object {$_.Name -like "*D365*"}
+```
+
+**Mac:**
+
+```bash
+# Test connection script
+./deployment/scripts/test-connection.sh dev --verbose
+
+# Check environment variables
+env | grep D365
+```
+
+**Step 3: Verify credentials**
+
+```javascript
+// Create test script: test-auth.js
+const config = require('./config/environments/dev.json');
+
+console.log('Testing configuration:');
+console.log('Org URL:', config.dynamics365.orgUrl);
+console.log('Client ID:', config.authentication.clientId ? 'Set' : 'Missing');
+console.log('Client Secret:', config.authentication.clientSecret ? 'Set' : 'Missing');
+
+// Run with: node test-auth.js
+```
+
+## Authentication Errors
+
+### Error: Azure AD authentication failed
+
+**Symptoms:**
+
+```
+AADSTS70011: The provided value for the input parameter 'scope' is not valid.
+AADSTS50105: The signed in user is not assigned to a role for the application
+```
+
+**Cause:** Azure AD application not properly configured
+
+**Solution:**
+
+**Step 1: Verify Azure AD app registration**
+
+```bash
+# Check app registration details
+az ad app show --id your-client-id --query "{displayName:displayName,appId:appId,replyUrls:replyUrls}"
+```
+
+**Step 2: Update app permissions**
+
+```bash
+# Add Dynamics 365 permissions
+az ad app permission add \
+  --id your-client-id \
+  --api 00000007-0000-0000-c000-000000000000 \
+  --api-permissions 78ce3f0f-a1ce-49c2-8cde-64b5c0896db4=Scope
+
+# Grant admin consent
+az ad app permission admin-consent --id your-client-id
+```
+
+**Step 3: Verify environment URLs**
+
+```javascript
+// Check URL configuration
+const config = require('./config/environments/dev.json');
+
+const urlChecks = [
+  { name: 'Org URL', url: config.dynamics365.orgUrl },
+  { name: 'Web API URL', url: config.dynamics365.webApiUrl },
+  { name: 'Tenant ID', value: config.dynamics365.tenantId },
+];
+
+urlChecks.forEach((check) => {
+  console.log(`${check.name}: ${check.url || check.value}`);
+});
+```
+
+## Environment Setup Errors
+
+### Error: Node.js version mismatch
+
+**Symptoms:**
+
+```
+error @types/node@18.0.0: The engine "node" is incompatible with this module.
+Expected version ">=18.0.0". Got "16.14.0"
+```
+
+**Cause:** Outdated Node.js version
+
+**Solution:**
+
+**Windows:**
+
+```powershell
+# Check current version
+node --version
+
+# Update using Chocolatey
+choco upgrade nodejs
+
+# Or using winget
+winget upgrade OpenJS.NodeJS
+
+# Verify update
+node --version
+npm --version
+```
+
+**Mac:**
+
+```bash
+# Check current version
+node --version
+
+# Update using Homebrew
+brew upgrade node
+
+# Or using nvm (recommended)
+nvm install 18
+nvm use 18
+nvm alias default 18
+
+# Verify update
+node --version
+npm --version
+```
+
+### Error: npm install fails with permission errors
+
+**Symptoms:**
+
+**Windows:**
+
+```
+npm ERR! Error: EPERM: operation not permitted, mkdir 'C:\Users\...\AppData\Roaming\npm'
+```
+
+**Mac:**
+
+```
+npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
+```
+
+**Solution:**
+
+**Windows:**
+
+```powershell
+# Configure npm for user directory
+npm config set prefix $env:USERPROFILE\npm-global
+npm config set cache $env:USERPROFILE\.npm-cache
+
+# Add to PATH
+$npmPath = "$env:USERPROFILE\npm-global"
+[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$npmPath", "User")
+
+# Clear and verify
+npm cache clean --force
+npm config list
+```
+
+**Mac:**
+
+```bash
+# Fix npm permissions
+sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
+
+# Or use nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.zshrc
+nvm install node
+nvm use node
+```
+
+## Git and Version Control Errors
+
+### Error: Line ending issues
+
+**Symptoms:**
+
+```
+warning: LF will be replaced by CRLF in package.json.
+The file will have its original line endings in your working directory
+```
+
+**Cause:** Different line ending conventions between Windows (CRLF) and Mac/Linux (LF)
+
+**Solution:**
+
+**Step 1: Configure Git globally**
+
+**Windows:**
+
+```powershell
+# Configure for cross-platform team
+git config --global core.autocrlf input
+git config --global core.eol lf
+```
+
+**Mac:**
+
+```bash
+# Configure for cross-platform team
+git config --global core.autocrlf input
+git config --global core.eol lf
+```
+
+**Step 2: Add .gitattributes file**
+
+```bash
+# Create .gitattributes in project root
+cat > .gitattributes << 'EOF'
+# Auto-detect text files and perform LF normalization
+* text=auto eol=lf
+
+# Force specific files to use LF
+*.js text eol=lf
+*.ts text eol=lf
+*.tsx text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+
+# Force shell scripts to use LF
+*.sh text eol=lf
+
+# Force PowerShell scripts to use CRLF
+*.ps1 text eol=crlf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.ico binary
+EOF
+```
+
+**Step 3: Normalize existing files**
+
+```bash
+# Remove all files from index
+git rm --cached -r .
+
+# Re-add all files with new line endings
+git add .
+
+# Commit the changes
+git commit -m "fix: normalize line endings"
+```
+
+### Error: Case sensitivity conflicts
+
+**Symptoms:**
+
+```
+error: The following untracked working tree files would be overwritten by merge:
+  src/components/myComponent.tsx
+```
+
+**Cause:** File renamed with different case, causing conflicts between case-sensitive (Mac) and
+case-insensitive (Windows) systems
+
+**Solution:**
+
+**Step 1: Check for case conflicts**
+
+**Windows:**
+
+```powershell
+# Find potential case conflicts
+Get-ChildItem -Recurse | Group-Object Name | Where-Object {$_.Count -gt 1}
+```
+
+**Mac:**
+
+```bash
+# Find case conflicts
+find . -type f | sort -f | uniq -di
+```
+
+**Step 2: Resolve conflicts**
+
+```bash
+# Rename file through Git (preserves history)
+git mv myComponent.tsx temp-component.tsx
+git mv temp-component.tsx MyComponent.tsx
+git commit -m "fix: correct component case"
+
+# Or force case change
+git config core.ignorecase false
+git add MyComponent.tsx
+git rm myComponent.tsx
+git commit -m "fix: correct component case"
+git config core.ignorecase true
+```
+
+## Package Management Errors
+
+### Error: Package-lock.json conflicts
+
+**Symptoms:**
+
+```
+npm ERR! peer dep missing: react@^18.0.0, required by @types/react@18.0.0
+```
+
+**Cause:** Inconsistent package versions or corrupted package-lock.json
+
+**Solution:**
+
+**Step 1: Clean package state**
+
+```bash
+# Remove node_modules and package-lock.json
+rm -rf node_modules package-lock.json  # Mac/Linux
+rmdir /s node_modules & del package-lock.json  # Windows (CMD)
+Remove-Item -Recurse -Force node_modules; Remove-Item package-lock.json  # Windows (PowerShell)
+
+# Clear npm cache
+npm cache clean --force
+```
+
+**Step 2: Reinstall packages**
+
+```bash
+# Fresh install
+npm install
+
+# Verify installation
+npm list --depth=0
+npm audit
+```
+
+**Step 3: Fix peer dependency issues**
+
+```bash
+# Install missing peer dependencies
+npm install react@^18.0.0
+
+# Or install all peer dependencies automatically
+npx install-peerdeps package-name
+```
+
+### Error: Native modules compilation fails
+
+**Symptoms:**
+
+**Windows:**
+
+```
+gyp ERR! find VS
+gyp ERR! find VS msvs_version not set from command line or npm config
+```
+
+**Mac:**
+
+```
+gyp: No Xcode or CLT version detected!
+```
+
+**Solution:**
+
+**Windows:**
+
+```powershell
+# Install Visual Studio Build Tools
+choco install visualstudio2019buildtools
+
+# Or configure npm to use specific VS version
+npm config set msvs_version 2019
+
+# Alternative: Use windows-build-tools
+npm install --global windows-build-tools
+```
+
+**Mac:**
+
+```bash
+# Install Xcode Command Line Tools
+xcode-select --install
+
+# Verify installation
+xcode-select -p
+gcc --version
+
+# If still failing, reset and reinstall
+sudo xcode-select --reset
+sudo xcode-select --install
+```
+
+## Runtime Errors
+
+### Error: Module resolution fails at runtime
+
+**Symptoms:**
+
+```
+Error: Cannot find module './components/MyComponent'
+```
+
+**Cause:** Path resolution issues between development and production environments
+
+**Solution:**
+
+**Step 1: Check build output**
+
+```bash
+# Examine built files
+ls -la dist/
+cat dist/index.js | grep MyComponent
+```
+
+**Step 2: Verify webpack configuration**
+
+```javascript
+// webpack.config.js
+const path = require('path');
+
+module.exports = {
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+      '@components': path.resolve(__dirname, 'src/components'),
+    },
+    extensions: ['.tsx', '.ts', '.js', '.jsx'],
+  },
+};
+```
+
+**Step 3: Update TypeScript paths**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@components/*": ["src/components/*"]
+    }
+  }
+}
+```
+
+### Error: Environment variables not loaded
+
+**Symptoms:**
+
+```
+TypeError: Cannot read property 'D365_CLIENT_ID' of undefined
+```
+
+**Cause:** Environment variables not properly loaded or configured
+
+**Solution:**
+
+**Step 1: Verify .env file location and format**
+
+```bash
+# Check .env.local exists in project root
+ls -la .env.local
+
+# Verify format (no spaces around =)
+cat .env.local
+```
+
+**Step 2: Load environment variables correctly**
+
+```javascript
+// At the top of your entry file
+require('dotenv').config({ path: '.env.local' });
+
+// Or use different files for different environments
+const dotenv = require('dotenv');
+const envFile = process.env.NODE_ENV === 'production' ? '.env.prod' : '.env.local';
+dotenv.config({ path: envFile });
+
+// Verify variables are loaded
+console.log('Environment variables loaded:', {
+  NODE_ENV: process.env.NODE_ENV,
+  D365_CLIENT_ID: process.env.D365_CLIENT_ID ? 'Set' : 'Missing',
+});
+```
+
+**Step 3: Platform-specific environment loading**
+
+**Windows:**
+
+```powershell
+# Check environment variables
+Get-ChildItem Env: | Where-Object {$_.Name -like "*D365*"}
+
+# Set temporarily for session
+$env:D365_CLIENT_ID = "your-client-id"
+
+# Set permanently
+[Environment]::SetEnvironmentVariable("D365_CLIENT_ID", "your-client-id", "User")
+```
+
+**Mac:**
+
+```bash
+# Check environment variables
+env | grep D365
+
+# Set temporarily for session
+export D365_CLIENT_ID="your-client-id"
+
+# Set permanently
+echo 'export D365_CLIENT_ID="your-client-id"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+---
+
+This guide covers the most frequently encountered errors in cross-platform Dynamics 365 development.
+For additional help, refer to the platform-specific troubleshooting guide or contact your team's
+platform champions.