Skip to content

Troubleshooting -- azemu

Common errors and their fixes.

TLS and certificate errors

x509: certificate signed by unknown authority

Cause: The self-signed certificate generated by azemu is not trusted by your system or by the tool making the request.

Fix (curl/CLI): Export the cert path from azemu's startup log:

export SSL_CERT_FILE=/var/folders/.../azemu-cert.pem
# Use the path printed by azemu on startup

Fix (macOS -- Terraform/Go clients): The azurerm provider uses Go's native TLS stack which checks the macOS keychain, not SSL_CERT_FILE:

security add-trusted-cert \
  -d -r trustRoot \
  -k ~/Library/Keychains/login.keychain-db \
  "$SSL_CERT_FILE"

Fix (Linux):

sudo cp "$SSL_CERT_FILE" /usr/local/share/ca-certificates/azemu.crt
sudo update-ca-certificates

Note: The certificate regenerates every time azemu starts unless you set AZEMU_CERT_PATH to a persistent PEM bundle file. With it set, the cert+key are loaded from disk on startup (or generated and written there on first run), so you only have to add it to the keychain once. The flox profile defaults this to .azemu/cert-bundle.pem for you. See docs/SETUP.md "Persistent (recommended)" for the full flow.

Cert errors after upgrading: bundle regenerated for *.vault.localhost

Cause: azemu now serves Key Vault data-plane traffic on per-vault hosts ({vaultName}.vault.localhost), which requires a *.vault.localhost SAN in the TLS certificate. On startup azemu checks the persisted bundle and regenerates it when the SAN is missing, so a bundle created by an older version is replaced and the previously trusted cert no longer matches.

Fix: Re-run the trust step for the regenerated bundle (macOS):

security add-trusted-cert \
  -d -r trustRoot \
  -k ~/Library/Keychains/login.keychain-db \
  .azemu/cert-bundle.pem

On Linux, repeat the update-ca-certificates flow above.

expected a URI in the format the-keyvault-name.vault.**

Cause: A Key Vault vaultUri (or a secret/key id parsed from state) does not use the per-vault host form. State written by an azemu version older than the host-based Key Vault routing carries path-style ids (https://localhost:4566/keyvault/{vault}/...) that the azurerm provider cannot parse.

Fix: Recreate the affected resources: terraform destroy (or terraform state rm for the key vault items) and re-apply against the current azemu so the new host-form ids are written to state. azemu state itself can be cleared with POST /api/state/reset.

Failed to connect to localhost port 4566/4567

Cause: The server is not running, or a previous azemu process is still holding the port.

Fix:

pkill -f "bin/azemu"
sleep 1
./bin/azemu

Terraform provider errors

Azure Stack is not supported

The AzureRM Provider supports the different Azure Public Clouds - including
China, Public, and US Government - however it does not support Azure Stack
due to differences in API and feature availability

Cause: The resourceManager URL in /metadata/endpoints uses http:// instead of https://. The azurerm provider classifies environments with non-HTTPS resource managers as Azure Stack and refuses to connect.

Fix: azemu changed so the ARM port (4566) serves HTTPS instead of HTTP. The metadata response now returns resourceManager: https://localhost:4566 which the provider recognises as a public-style cloud. Both ports 4566 and 4567 share the same self-signed certificate.

retrieving metadata from endpoint: ... dial tcp [::1]:4567: connection refused

Cause: Terraform resolves localhost to IPv6 (::1) but the server only listens on IPv4.

Fix:

export ARM_METADATA_HOSTNAME=127.0.0.1:4567

Attribute "skip_provider_registration" is deprecated

Cause: The azurerm provider v4.x deprecated skip_provider_registration.

Fix: Use the replacement:

resource_provider_registrations = "none"

flox errors

no such command or positional: exec

Cause: The subcommand syntax changed. Use activate -c instead.

Fix:

# Wrong
flox exec -- terraform version

# Correct
flox activate -c "terraform version"

Environment can't be activated whilst there are existing activations in 'run' mode

Cause: Stale background processes from a previous session.

Fix: Kill the PIDs listed in the error, or run:

kill $(pgrep -f "flox")

Compilation errors

cannot assign to r.NotFound

Cause: chi v5 uses r.NotFound(handler) as a method call, not a field assignment.

Fix:

// Wrong
r.NotFound = handler

// Correct
r.NotFound(handler)

Operational notes

Both ports now use HTTPS

As of the Phase 1 terraform integration fix, azemu serves HTTPS on both ports:

  • :4566 (HTTPS) -- ARM API, data plane
  • :4567 (HTTPS) -- metadata service, OAuth2, OIDC

Both ports share the same self-signed certificate. All curl commands must use -k (skip verification) or have the cert trusted by your system. The make smoke target includes -k flags.

Cloud classification depends on the metadata URL scheme

The azurerm provider fetches https://{metadata_host}/metadata/endpoints and inspects the resourceManager field to determine which Azure cloud the environment represents:

URL scheme Azure provider classification Result
https://... Public-style cloud Accepted
http://... Azure Stack Rejected

azemu works around this by serving ARM on HTTPS at :4566 and declaring resourceManager: https://localhost:4566 in the metadata response.