pos-system/microservices/.agent/skills/development-lifecycle/references/build-errors.md

Common Build Errors Catalog

Quick reference for troubleshooting .NET and Docker build errors in GoodGo microservices.

.NET Build Errors

CS0246: Type or namespace not found

Error:

error CS0246: The type or namespace name 'X' could not be found

Common Causes:

1. Missing package reference
2. Incorrect namespace
3. Package not restored

Solutions:

# 1. Restore packages
dotnet restore

# 2. Add missing package
dotnet add package <PackageName>

# 3. Check using statements
# Add: using YourNamespace;

# 4. Clean and rebuild
dotnet clean && dotnet build

---

CS0103: Name does not exist in current context

Error:

error CS0103: The name 'X' does not exist in the current context

Common Causes:

1. Missing using directive
2. Typo in variable/method name
3. Wrong scope

Solutions:

// Add using directive
using System.Linq;
using Microsoft.EntityFrameworkCore;

// Check variable is in scope
public void Method()
{
    var item = new Item();
    // item is only available within Method()
}

---

CS1061: Does not contain a definition

Error:

error CS1061: 'Type' does not contain a definition for 'Member'

Common Causes:

1. Typo in property/method name
2. Wrong NuGet package version
3. Extension method not imported

Solutions:

// 1. Check spelling
order.Items // not order.Item

// 2. Import extension methods
using System.Linq; // for .Where(), .Select(), etc.

// 3. Update package version
dotnet list package --outdated
dotnet add package Microsoft.EntityFrameworkCore --version 10.0.0

---

NU1101: Unable to find package

Error:

error NU1101: Unable to find package 'X'. No packages exist with this id

Solutions:

# 1. Check package name (spelling)
dotnet add package Swashbuckle.AspNetCore # not Swashbuckle.AspNet

# 2. Check NuGet sources
dotnet nuget list source

# 3. Clear NuGet cache
dotnet nuget locals all --clear

# 4. Restore with verbose
dotnet restore -v detailed

---

MSB3277: Version conflicts

Error:

warning MSB3277: Found conflicts between different versions of "X"

Solutions:

<!-- Directory.Build.props or .csproj -->
<ItemGroup>
  <!-- Force specific version across all projects -->
  <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.2" />
</ItemGroup>

# Or update all references
dotnet add package Microsoft.EntityFrameworkCore --version 10.0.2

---

Docker Build Errors

Cannot connect to Docker daemon

Error:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Solutions:

# 1. Start Docker Desktop (macOS/Windows)
open -a Docker

# 2. Check Docker status
docker info

# 3. Restart Docker daemon (Linux)
sudo systemctl restart docker

---

Context error: Dockerfile not found

Error:

ERROR: failed to solve: failed to read dockerfile: failed to resolve path

Common Causes:

• Wrong build context
• Dockerfile in wrong location

Solutions:

# Correct: Build from repo root with context
docker build -t my-service -f services/my-service-net/Dockerfile .

# ❌ Wrong: Building from service directory
cd services/my-service-net
docker build -t my-service .

# ✅ Correct: Specify context
docker build -t my-service -f Dockerfile ../..

---

COPY failed: file not found

Error:

ERROR: failed to copy files: file not found

Common Cause: Wrong COPY path in Dockerfile

Solutions:

# ❌ Wrong: Path relative to Dockerfile location
COPY src/ /app/

# ✅ Correct: Path relative to build context (repo root)
COPY services/my-service-net/src/ /app/

---

Docker build cache issues

Problem: Old files being used despite changes

Solutions:

# Build without cache
docker build --no-cache -t my-service .

# Or via docker-compose
docker-compose build --no-cache my-service-net

# Clear all build cache
docker builder prune -a

---

Entity Framework Errors

No migrations found

Error:

No migrations were found

Solutions:

# Create initial migration
dotnet ef migrations add InitialCreate --project src/MyService.Infrastructure

# Verify migrations folder exists
ls src/MyService.Infrastructure/Migrations/

---

Connection string error

Error:

A connection string could not be constructed

Solutions:

# 1. Add connection string to appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=mydb;..."
  }
}

# 2. Set environment variable
export ConnectionStrings__DefaultConnection="Host=..."

# 3. Verify in Program.cs
builder.Services.AddDbContext<MyContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

---

Quick Troubleshooting Checklist

When build fails:

• Run dotnet restore
• Check for typos
• Verify using statements
• Check package versions (dotnet list package)
• Clean build: dotnet clean && dotnet build
• Check build logs: dotnet build -v detailed
• Clear NuGet cache: dotnet nuget locals all --clear

When Docker build fails:

• Check Docker daemon is running
• Verify build context path
• Check Dockerfile COPY paths
• Try --no-cache build
• Check .dockerignore file
• Verify base image exists

---

Related Resources

• Test Failures Guide
• Debugging Guide
• Main Skill: development-lifecycle