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:**
```bash
# 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:**
```csharp
// 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:**
```csharp
// 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:**
```bash
# 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:**
```xml
<!-- Directory.Build.props or .csproj -->
<ItemGroup>
  <!-- Force specific version across all projects -->
  <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.2" />
</ItemGroup>
```

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```dockerfile
# ❌ 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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](test-failures.md)
- [Debugging Guide](debugging-guide.md)
- Main Skill: [development-lifecycle](../SKILL.md)