Troubleshooting

This guide helps you resolve common issues you might encounter when using Pika Framework.

Quick Diagnosis

Check Your Environment

First, verify your setup:

# Check Node.js version (should be 22+)
node --version

# Check pnpm version
pnpm --version

# Check Pika CLI version
pika --version

# Check AWS CLI (if using AWS features)
aws --version

Common Error Patterns

• Installation Issues: Node.js version, pnpm installation, permissions
• Build Errors: TypeScript compilation, missing dependencies
• Deployment Issues: AWS credentials, CDK bootstrap, IAM permissions
• Runtime Errors: Environment variables, network connectivity, AWS service limits

Installation Issues

Node.js Version Problems

Solution:

# Check current version
node --version

# Update Node.js with Homebrew
brew upgrade node

pnpm Installation Issues

Solution:

# Use the official installer (recommended)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Verify installation
pnpm --version

Build Issues

TypeScript Compilation Errors

Solution:

# Run in root of project, removes all .turbo, node_modules, etc.
pnpm run clean

# In root, install all deps
pnpm install

# In root, try to build everything
pnpm build

# In root, check typescript types
pnpm run check-types

Missing Dependencies

Solution:

# Reinstall all dependencies
pnpm install

# Clear pnpm cache
pnpm store prune

# Check for workspace issues
pnpm list --depth=0

Build Script Failures

Solution:

# Check build logs for specific errors
pnpm build --verbose

# Check for environment-specific issues
echo $NODE_ENV

Deployment Issues

AWS Credentials Not Configured

Solution:

# Configure AWS CLI
aws configure

# Verify credentials
aws sts get-caller-identity

CDK Bootstrap Required

Solution:

# Bootstrap CDK in your account/region
cdk bootstrap

# Verify bootstrap
aws cloudformation describe-stacks --stack-name CDKToolkit

Insufficient IAM Permissions

Solution:

• Ensure your AWS user has the necessary permissions
• Use an IAM role with appropriate permissions
• Contact your AWS administrator for proper permissions

Required permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["cloudformation:*", "s3:*", "lambda:*", "apigateway:*", "iam:*", "logs:*", "cloudwatch:*"],
            "Resource": "*"
        }
    ]
}

Domain Configuration Issues

Solution:

# Verify certificate exists
aws acm list-certificates --region us-east-1

# Check certificate ARN format
# Should be: arn:aws:acm:region:account:certificate/cert-id

VPC Configuration Issues

Solution:

# List VPCs
aws ec2 describe-vpcs

Runtime Issues

Frontend Not Loading

Solution:

# Check if development server is running
lsof -i :3000

# Check for build errors
cd apps/pika-chat && pnpm build

Backend Services Not Responding

Solution:

# Check if services are deployed
aws cloudformation describe-stacks --stack-name mycompany-pika

Authentication Issues

Solution:

# Check authentication provider configuration
cat apps/pika-chat/src/lib/server/auth-provider/index.ts

# Check browser cookies and local storage
# Clear browser cache and cookies if needed

Sync Issues

Sync Command Fails

Solution:

# Check internet connection
ping github.com

# Use debug mode for more information
pika sync --debug

Unexpected File Overwrites

Solution:

# Check sync configuration
cat .pika-sync.json

# Add files to userProtectedAreas
# Edit .pika-sync.json and add:
"userProtectedAreas": ["my-custom-file.ts"]

Merge Conflicts

Solution:

# Review conflicts
pika sync --diff

# Resolve conflicts manually
# Edit conflicted files and remove conflict markers

Debugging Tools

Enable Debug Logging

# Enable debug mode for various commands
pika sync --debug
pnpm run dev -- --debug
cdk deploy --debug

# Check environment variables
env | grep -i pika
env | grep -i aws

Log Analysis

# View recent logs
aws logs tail /aws/lambda/mycompany-pika-service --follow

Performance Monitoring

# Check Lambda function performance
aws cloudwatch get-metric-statistics \
    --namespace AWS/Lambda \
    --metric-name Duration \
    --dimensions Name=FunctionName,Value=mycompany-pika-service \
    --start-time 2024-01-01T00:00:00Z \
    --end-time 2024-01-02T00:00:00Z \
    --period 3600 \
    --statistics Average,Maximum

Getting Help

Before Asking for Help

1. Check this troubleshooting guide for your specific issue
2. Search existing issues on the GitHub repository
3. Check the documentation for your specific use case
4. Try the solutions above for common issues

When Creating an Issue

Environment details:

• Operating system and version
• Node.js version
• pnpm version
• Pika CLI version

Error details:

• Exact error message
• Steps to reproduce
• Expected vs actual behavior

Debug information:

• Console output with --debug flag
• Relevant log files
• Configuration files (without sensitive data)

What you've tried:

• Solutions attempted
• Workarounds that work/don't work

Community Resources

• GitHub Issues: https://github.com/rithum/pika/issues
• GitHub Discussions: https://github.com/rithum/pika/discussions
• Documentation: https://github.com/rithum/pika

Still having issues? Create a detailed issue on GitHub with all the information above, and the community will help you resolve it!