Troubleshooting

Common problems and their solutions.

Build

Build fails: "No buildpack detected"

Buildpacks couldn't detect the project language.

Solution: Make sure there's a marker file in the project root (or in the path from .hive.yml):

Language	Marker file
Go	go.mod
Python	requirements.txt, setup.py, or Pipfile
Node.js	package.json
.NET	*.csproj or *.sln
Java	pom.xml or build.gradle

Build fails: Docker daemon not available

Cannot connect to the Docker daemon

Solution: hive build requires a Docker daemon. In CI, make sure docker:27-dind is specified as a service. Locally, Docker Desktop must be running.

Build fails: Dockerfile not used

The default builder is paketo. Even if a Dockerfile exists, Hive won't use it unless you explicitly set:

builder: docker

Without this, Paketo analyzes the project files and picks a buildpack based on marker files (package.json, go.mod, nginx.conf, etc.). The Dockerfile is ignored entirely.

Build fails: Paketo picks wrong buildpack

"server" directive is not allowed here in /workspace/nginx.conf:1

Cause: Paketo detects files and picks a buildpack by pattern matching. If your project has an nginx.conf (even if it's meant for a Dockerfile COPY step), Paketo will use the nginx buildpack and treat it as the main nginx config. Similarly, a package.json used only for tooling can trigger the Node.js buildpack.

Common conflicts:

File in project	Paketo thinks	Actually used for
nginx.conf	nginx static site	COPY into Dockerfile
package.json	Node.js app	Frontend build tooling
requirements.txt	Python app	Build-time dependency

Solution: Add builder: docker to .hive.yml when your project uses a Dockerfile with a multi-stage build or when Paketo misdetects the project type.

Build slow: downloading builder each time

Solution: The buildpack builder is cached in Docker. If the cache isn't preserved between CI runs, that's normal for dind. First build will be slow (~3-5 minutes), subsequent ones faster.

---

Test

Test fails: timeout

Health check timed out after 30s

Causes:

1. Service takes longer than 30 seconds to start — increase timeout: hive test --timeout 60
2. Wrong healthPath — check that the endpoint exists and returns 2xx
3. Wrong port — service listens on a different port

Test fails: container exited

Container exited with code 1

The container crashed on startup. Check the logs in the JUnit report or run the container manually:

docker run -p 8080:8080 <image>

Test fails: connection refused

The service started but isn't listening on the specified port.

Check: the service must listen on 0.0.0.0, not 127.0.0.1 or localhost. Inside a container, localhost refers only to the container itself.

---

Deploy

Deploy stuck: ArgoCD sync pending

ArgoCD can't sync the application.

Check:

1. ArgoCD UI: https://argocd.stage.svcik.org (staging) or https://argocd.svcik.org (production)
2. Find your application: {namespace}-{name}
3. Look at Events and Sync Status

Deploy fails: ImagePullBackOff

Failed to pull image: unauthorized

Causes:

1. Image not built — make sure the build succeeded
2. Registry credentials — check that CI_REGISTRY_USER and CI_REGISTRY_PASSWORD are available
3. Different project — in GitLab CI/CD Settings, you need to allow pull from the hive-api project

Deploy fails: namespace not found

Solution: The namespace is created automatically on first deploy via ArgoCD (CreateNamespace=true). If the problem persists, contact the platform team.

---

Service not accessible

URL not responding

After a successful deploy, the service should be accessible at:

https://{name}.{namespace}.knative-staging.svcik.org  (staging)
https://{name}.{namespace}.knative.svcik.org          (production)

Check:

1. Correct URL — hive list shows names, namespace comes from .hive.yml or git remote
2. Knative revision — check in ArgoCD that the KnativeService was created
3. TLS — wildcard certificate is created automatically but may take a couple of minutes

Old version of service after deploy

Knative uses revisions. If a new revision doesn't pass probes, Knative continues serving the old version.

Check:

1. Look at revision status in ArgoCD
2. Check healthPath — the new version might respond on a different path
3. Check lifecycle — the startup probe might be timing out

This is a safeguard, not a bug

Knative intentionally keeps the old revision until the new one passes all probes. This prevents downtime.

---

CI Pipeline

Pipeline doesn't start

Check:

1. Push to default branch (usually main or master)
2. .gitlab-ci.yml in the repository root
3. Pipeline is not disabled in Settings → CI/CD

generate-pipeline fails

No .hive.yml files found

Solution: hive ci --global searches for .hive.yml from the repository root. Make sure the file exists and is named exactly .hive.yml (with a leading dot).

---

Still not working?

Contact the platform team with the following information:

1. Link to the failed pipeline
2. Service name and namespace
3. Contents of .hive.yml
4. Description of the problem