NX Cache Issues & Solutions

This document provides troubleshooting steps for common NX cache-related issues encountered in our workspace.

Common Issues

1. Cache Corruption Error

Error Message:

Error: ENOENT: no such file or directory, open '/Users/.../editor/.nx/cache/terminalOutputs/[hash]'
    at writeFileSync (node:fs:2426:20)
    at ForkedProcessTaskRunner.writeTerminalOutput

Symptoms:

• Build commands fail with filesystem errors
• NX cannot write to cache directory
• Persistent across multiple attempts

Root Cause:

• Corrupted NX cache directory structure
• Missing terminal output directories
• Permission issues with cache files

2. Cache Issues with --skip-nx-cache

Error Message:

Error: ENOENT: no such file or directory, open '/.../editor/.nx/cache/terminalOutputs/[hash]'

Symptoms:

• Occurs even when using --skip-nx-cache flag
• Build succeeds but terminal output writing fails
• Hash numbers in error path change between runs

Root Cause:

• --skip-nx-cache only skips build result caching
• Terminal output logging still uses cache directory
• Missing terminalOutputs directory structure

3. TypeScript Declaration File Conflicts

Error Message:

error TS6059: File '/.../src/lib/models/responsive/index.ts' is not under 'rootDir' 'libs/core-types'. 
'rootDir' is expected to contain all source files.

Symptoms:

• TypeScript compilation errors during build
• Files reported as "not under rootDir"
• Build artifacts in source directories

Root Cause:

• .d.ts declaration files present in src/ directories
• TypeScript compiler confusion between source and build artifacts

Solutions

Quick Fix: Alternative Cache Directory

When encountering cache corruption, use an alternative cache directory:

# Use temporary cache directory
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build [project-name] --configuration=production

# Example
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --configuration=production

# Even with --skip-nx-cache, terminal outputs still use cache
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --verbose --skip-nx-cache

Important Note: The --skip-nx-cache flag only skips build result caching, but NX still writes terminal outputs to the cache directory. Use the NX_CACHE_DIRECTORY environment variable for complete cache redirection.

Complete Cache Reset

For persistent issues, perform a complete cache reset:

# Method 1: Remove and reset
rm -rf .nx && nx reset

# Method 2: Manual cleanup
rm -rf .nx/cache
mkdir -p .nx/cache/terminalOutputs
nx reset

Fix Declaration File Conflicts

Remove build artifacts from source directories:

# Remove all .d.ts files from source directories
find libs -name "*.d.ts" -path "*/src/*" -not -path "*/node_modules/*" -delete

# Verify specific library
find libs/core-models/src -name "*.d.ts" -delete

Create Missing Cache Directories

If specific cache files are missing:

# Create missing directories
mkdir -p .nx/cache/terminalOutputs

# Create specific missing file (replace hash with actual hash from error)
touch .nx/cache/terminalOutputs/[hash-from-error]

Permanent Solution: Helper Script

Create a build script that always works:

# Create build-nx.sh in project root
cat > build-nx.sh << 'EOF'
#!/bin/bash
# Reliable NX build script that handles cache issues

PROJECT=${1:-editor-web}
CONFIG=${2:-production}

echo "🚀 Building $PROJECT with configuration $CONFIG..."

# Use alternative cache directory to avoid local cache corruption
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build $PROJECT --configuration=$CONFIG

echo "✅ Build completed successfully!"
EOF

chmod +x build-nx.sh

# Usage:
./build-nx.sh editor-web production
./build-nx.sh core-types

Prevention Strategies

1. Gitignore Configuration

Ensure your .gitignore includes:

# NX Cache
.nx/cache
.nx/workspace-data

# TypeScript build artifacts in source
src/**/*.d.ts
libs/**/src/**/*.d.ts

2. Regular Cache Maintenance

Add to your development workflow:

# Weekly cache cleanup
nx reset

# Before major builds
rm -rf .nx/cache && nx reset

3. Build Script Wrapper

Create a robust build script that handles cache issues:

#!/bin/bash
# build-with-fallback.sh

PROJECT=$1
CONFIG=${2:-production}

echo "Building $PROJECT with configuration $CONFIG..."

# Try normal build first
if nx build $PROJECT --configuration=$CONFIG; then
    echo "✅ Build successful"
    exit 0
fi

echo "⚠️ Build failed, trying with alternative cache..."

# Fallback to alternative cache
if NX_CACHE_DIRECTORY=/tmp/nx-cache nx build $PROJECT --configuration=$CONFIG; then
    echo "✅ Build successful with alternative cache"
    exit 0
fi

echo "❌ Build failed with both methods"
exit 1

Diagnostic Commands

Check Cache Status

# Check NX daemon status
nx daemon --help

# View cache information
nx show projects --affected

# Check workspace integrity
nx workspace-lint

Identify Problem Files

# Find declaration files in source
find . -name "*.d.ts" -path "*/src/*" | head -10

# Check cache directory structure
ls -la .nx/cache/

# Verify permissions
ls -la .nx/

Emergency Recovery

If all else fails, perform a complete workspace reset:

# 1. Stop all NX processes
nx daemon --stop

# 2. Clean all build artifacts
rm -rf dist/
rm -rf .nx/
rm -rf node_modules/.cache/

# 3. Reinstall dependencies (if needed)
yarn install

# 4. Reset NX
nx reset

# 5. Rebuild from scratch
nx build [project-name] --configuration=production

Known Working Configurations

Successful Build Commands

# Editor Web (Production) - RECOMMENDED METHOD ✅
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --configuration=production

# With --skip-nx-cache flag (still needs cache directory for terminal outputs) ✅
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --verbose --skip-nx-cache

# Build all projects ✅
NX_CACHE_DIRECTORY=/tmp/nx-cache npx nx run-many -t build

# Core Types Library ✅
nx build core-types

# With verbose output for debugging ✅
NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --configuration=production --verbose

NX Cloud Connection

# Correct way to connect to NX Cloud ✅
npx nx connect

# WRONG (will fail) ❌:
yarn nx connect
yarn -y nx@latest connect

Environment Variables

# Disable cache entirely (not recommended for regular use)
NX_CACHE_DIRECTORY=/dev/null nx build [project]

# Use custom cache location
export NX_CACHE_DIRECTORY=/tmp/nx-cache
nx build [project]

Related Issues

• Bundle size warnings (see bundle configuration in apps/*/project.json)
• TypeScript compilation errors (check tsconfig.*.json files)
• Angular compiler warnings (unused imports/components)

Summary

✅ WORKING SOLUTIONS

Method 1: Environment Variable (Recommended)

NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --configuration=production

Method 2: Helper Script (Easiest)

./build-nx.sh editor-web production
./build-nx.sh core-types

🔧 Key Findings

• --skip-nx-cache only skips build result caching, NOT terminal output caching
• Terminal outputs still require a writable cache directory
• Using NX_CACHE_DIRECTORY=/tmp/nx-cache redirects ALL cache operations
• NX Cloud connection: Use npx nx connect (not yarn)

🚨 What NOT to Do

• Don't use nx build without cache redirection if cache is corrupted
• Don't use yarn nx connect for NX Cloud setup
• Don't expect --skip-nx-cache to solve cache directory issues

Last Updated

Document created: 2025-01-16 Last incident resolved: 2025-01-16 Status: All major cache issues resolved ✅ Build method confirmed working: NX_CACHE_DIRECTORY=/tmp/nx-cache nx build editor-web --verbose --skip-nx-cache