Troubleshooting

Common Issues and Solutions

This guide covers the problems you are most likely to run into and how to solve them. If your issue is not listed here, check the FAQ or run vandor vpkg doctor as a starting point.

Installation Issues

Vandor command not found

Problem:

vandor: command not found

Solution:

Check if Vandor is in your PATH:

which vandor

If not found, reinstall or add the install directory to your PATH:

# Reinstall
go install github.com/alfariiizi/vandor/cli@latest

# Or add Go bin to PATH
export PATH=$PATH:$(go env GOPATH)/bin
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

Wrong Go version

Problem:

Error: requires Go 1.24 or higher

Solution:

Update Go to 1.24+:

go version
# If below 1.24, update Go from https://go.dev/dl/

Sync Issues

Sync regenerates *_gen.go wiring files based on your filesystem structure. Most wiring problems are solved by syncing.

Generated code is outdated

Problem:

Error: undefined: NewCreateOrder
# or
Error: missing type *application.CreateOrder

Solution:

Regenerate all wiring files:

vandor sync all
go mod tidy

Sync shows unexpected changes

Problem:

Running sync would change files you did not expect.

Solution:

Use the check flag to preview changes without applying them:

vandor sync --check

This shows what sync would do without actually modifying anything. Review the output, then run vandor sync all when you are comfortable.

FX dependency injection errors

Problem:

Error: no provider found for type *application.CreateOrder
Error: missing type X

This means a use case, service, or infrastructure dependency is not wired into the FX graph.

Solution:

1. Run sync to regenerate module wiring:

vandor sync all

2. If the error persists, check that the component's constructor is exported (starts with a capital letter):

// Correct -- exported constructor
func NewCreateOrder(repo port.OrderRepository) *CreateOrder { ... }

// Wrong -- unexported constructor
func newCreateOrder(repo port.OrderRepository) *createOrder { ... }

3. Verify the component exists on disk in the expected location. Sync reads your filesystem, so if the file is missing or in the wrong directory, it will not be wired.

Package Issues

Package installation fails

Problem:

Error: failed to install package @official/http-humachi

Solution:

1. Check your internet connection
2. Try with verbose output for more details:

vandor vpkg add @official/http-humachi --verbose

3. Make sure the package name is correct:

vandor vpkg search http

Package not working after install

Problem:

Installed a package but the application does not recognize it.

Solution:

Run the doctor to diagnose:

vandor vpkg doctor

If issues are found, try auto-fixing:

vandor vpkg doctor --fix

Then sync to make sure wiring is up to date:

vandor sync all

Doctor reports issues

Problem:

vandor vpkg doctor shows errors or warnings.

Solution:

The doctor output tells you exactly what is wrong. Common fixes:

# Auto-fix configuration and wiring issues
vandor vpkg doctor --fix

# If that does not resolve it, sync and tidy
vandor sync all
go mod tidy

For issues that require manual attention, the doctor describes what needs to change and where.

Build Issues

Import cycle detected

Problem:

Error: import cycle not allowed in package

This happens when contexts reference each other in a circular way.

Solution:

1. Use interface segregation -- import specific interfaces, not entire contexts:

// Wrong -- importing entire context
import "project/internal/core/contexts/user"

// Right -- import the specific interface you need
import userApp "project/internal/core/contexts/user/application"

type CreateOrder struct {
    userValidator userApp.UserValidator  // Interface only
}

2. Regenerate wiring:

vandor sync all
go mod tidy

3. Review your context dependencies. If two contexts need each other, consider whether they should be one context or whether you need a shared contract.

Package not found errors

Problem:

Error: package project/internal/core/contexts/order not found

Solution:

# Make sure Go dependencies are clean
go mod tidy

# Regenerate wiring
vandor sync all

# Verify your go.mod module name matches your imports

Build fails after adding context

Problem:

Added a new context but the build fails.

Solution:

Adding a context should trigger an automatic sync, but if something went wrong:

# Sync all wiring
vandor sync all

# Clean Go module state
go mod tidy

# Try building
go build ./cmd/app

Development Issues

Hot reload not working

Problem:

Changes are not reflected when running vandor dev:app.

Solution:

1. Make sure you are editing files in the watched directories (typically internal/, cmd/, config/)
2. Check if the dev server is actually running -- look for output in your terminal
3. Stop and restart:

# Stop the current dev server (Ctrl+C)
# Start again
vandor dev:app

Application will not start

Problem:

Error: bind: address already in use

Solution:

The port is already in use by another process.

1. Change the port in your config:

# config/runner/app.yaml or config/base.yaml
http:
  port: 8081  # Change from 8080

2. Or kill the process using the port:

# Find what is using the port
lsof -i :8080

# Kill it
kill -9 <PID>

Database connection failed

Problem:

Error: failed to connect to database

Solution:

1. Verify the database is running:

docker ps | grep postgres

2. Check your configuration:

# config/base.yaml
database:
  url: postgres://user:pass@localhost:5432/mydb

3. If using environment variables, verify they are set:

echo $DATABASE_URL

Configuration Issues

Config file not found

Problem:

Error: config file not found

Solution:

Vandor v0.4 uses a structured config directory:

config/
  base.yaml          # Shared configuration
  runner/
    app.yaml          # App-specific config
    worker.yaml       # Worker-specific config

Make sure config/base.yaml exists. If you are starting a new project, vandor new creates this for you. If the file is missing, create it:

# config/base.yaml
app:
  name: myapp
  env: development

Environment variables not loading

Problem:

Set environment variables but they are not being used.

Solution:

Check your config files reference environment variables correctly. Also verify the variables are exported in your shell:

# Set and export
export DATABASE_URL=postgres://user:pass@localhost:5432/mydb

# Verify
echo $DATABASE_URL

For development, you can use a .env file in your project root. Make sure it is not committed to git (add .env to .gitignore).

Runner config not applying

Problem:

Configuration in config/runner/app.yaml does not seem to take effect.

Solution:

Runner configs override config/base.yaml. Check that:

1. The file name matches the runner you are using (app.yaml for vandor run:app / vandor dev:app)
2. The YAML structure is valid
3. You restarted the application after changing config

# Restart to pick up config changes
vandor dev:app

Code Generation Issues

Context structure looks wrong

Problem:

Generated context does not have the expected directories.

Solution:

Contexts follow a fixed structure in v0.4:

internal/core/contexts/<context>/
  domain/         # Entities, value objects, repository interfaces
  application/    # Use cases, services
  module.go       # FX module definition
  module_gen.go   # Generated wiring (managed by sync)

If directories are missing, add components to create them:

vandor add usecase catalog create_product
vandor add service catalog price_calculator

Sync does not pick up my changes

Problem:

Added a new file but vandor sync all does not include it in the wiring.

Solution:

Sync reads your filesystem to discover components. Make sure:

1. Your file is in the correct directory (e.g., application/ for use cases)
2. The file follows naming conventions
3. The constructor function is exported

If you added a file manually (not through vandor add), sync should still detect it as long as it follows the conventions. Run:

vandor sync all

Performance Issues

Slow sync

Problem:

vandor sync all takes a long time.

Solution:

Sync is typically fast (under a second). If it is slow:

1. Check that your project does not have an unusually large number of files in the scanned directories
2. Use targeted sync instead of syncing everything:

vandor sync context catalog

Large binary size

Problem:

The compiled binary is larger than expected.

Solution:

Build with optimization flags:

go build -ldflags="-s -w" -o bin/app ./cmd/app

The -s flag removes the symbol table and -w removes debug information. This typically reduces binary size by 20-30%.

Prevention Tips

1. Run vandor sync all after adding components -- This keeps wiring up to date
2. Run vandor vpkg doctor when something breaks -- The doctor catches most package-related issues
3. Run go mod tidy regularly -- Keeps Go dependencies clean
4. Check vandor sync --check before committing -- Verify no wiring changes are pending
5. Keep Vandor CLI updated -- vandor upgrade pulls the latest fixes

Getting More Help

If your issue is not covered here:

1. Check the FAQ for common questions
2. Review the Guides for workflow walkthroughs
3. Look at the CLI Reference for command details
4. Check GitHub issues at github.com/alfariiizi/vandor

When reporting an issue, include:

1. Vandor version: vandor version
2. Go version: go version
3. Operating system
4. Full error message
5. Steps to reproduce
6. Output of vandor vpkg doctor