Skip to main content

Troubleshooting

Solutions to common issues and how to debug problems in Sluice.

Troubleshooting

This guide covers common issues and how to resolve them.

Pipeline Issues

Pipeline Won’t Start

Symptoms: Clicking “Run Pipeline” does nothing or returns an error.

Possible Causes:

  1. No stages defined - Pipeline needs at least one stage
  2. Invalid configuration - Syntax errors in YAML/JSON
  3. Missing permissions - User lacks run permissions

Solutions:

  1. Add at least one stage to your pipeline
  2. Validate your configuration using the editor’s syntax check
  3. Contact your tenant admin for permission issues

Pipeline Stuck in “Running”

Symptoms: Pipeline shows “Running” but no progress.

Possible Causes:

  1. Stage timeout - Stage exceeded its timeout
  2. Worker unavailable - No workers to process the job
  3. External dependency - Waiting on external service

Solutions:

  1. Check stage logs for timeout messages
  2. Verify workers are healthy in the system status
  3. Cancel the run and investigate logs

Build Stage Issues

Docker Build Failed

Symptoms: Build stage fails with Docker errors.

Common Errors:

“Dockerfile not found”

error: unable to prepare context: unable to evaluate symlinks in Dockerfile path

Solution: Verify the dockerfile path is correct relative to your repository root.

config:
  dockerfile: ./Dockerfile       # Common
  dockerfile: ./docker/Dockerfile  # If in subdirectory

“Failed to fetch image”

error: failed to fetch image: manifest unknown

Solution: Check that your base image exists and is accessible.

# Use specific tags, not :latest for reproducibility
FROM node:18-alpine

“Out of disk space”

error: write /var/lib/docker/...: no space left on device

Solution: Your image or build cache is too large. Consider:

  • Using smaller base images (Alpine variants)
  • Adding .dockerignore to exclude unnecessary files
  • Multi-stage builds to reduce final image size

Registry Push Failed

Symptoms: Build succeeds but push to registry fails.

Possible Causes:

  1. Authentication failed - Invalid or expired credentials
  2. Repository doesn’t exist - Need to create repository first
  3. Permission denied - Missing push access

Solutions:

  1. Update registry credentials in settings
  2. Create the repository in your registry
  3. Verify push permissions for your account

Deploy Stage Issues

Kubernetes Deployment Failed

Symptoms: Deploy stage fails when applying to Kubernetes.

“Namespace not found”

error: namespaces "production" not found

Solution: Create the namespace first or add it to your manifests:

apiVersion: v1
kind: Namespace
metadata:
  name: production

“Image pull failed”

error: failed to pull image: ImagePullBackOff

Solution: Verify:

  1. Image exists in registry
  2. Registry credentials configured in Kubernetes
  3. Image tag is correct
# Check image pull secret
kubectl get secret regcred -n your-namespace

“Insufficient resources”

error: 0/3 nodes are available: insufficient cpu

Solution: Reduce resource requests or add cluster capacity:

resources:
  requests:
    cpu: '100m' # Reduce from "500m"
    memory: '128Mi'

Helm Deployment Failed

Symptoms: Helm deploy stage fails.

“Chart not found”

Solution: Verify chart path is correct:

config:
  type: helm
  chart: ./charts/my-app # Relative to repository root

“Values validation failed”

Solution: Check your values match the chart’s schema. Use helm lint locally to validate.

Webhook Issues

Webhooks Not Triggering

Symptoms: Push to repo, but no pipeline runs.

Checklist:

  1. Verify webhook URL is correct in Git provider
  2. Check webhook secret matches
  3. Confirm webhook is active/enabled
  4. Review recent deliveries for errors

Signature Validation Failed

Symptoms: Webhook received but rejected with 401/403.

Solution:

  1. Go to pipeline settings in Sluice
  2. Copy the webhook secret
  3. Update the secret in your Git provider
  4. Test with a new push

Authentication Issues

“Unauthorized” Errors

Symptoms: API calls return 401 errors.

Solutions:

  1. Token expired - Generate a new API token
  2. Wrong tenant - Verify you’re using the correct tenant ID
  3. Permissions - Contact admin for role assignment

SSO Login Failed

Symptoms: Cannot log in via SSO.

Solutions:

  1. Clear browser cache and cookies
  2. Try incognito/private window
  3. Contact your identity provider admin
  4. Verify SSO is configured correctly

Performance Issues

Slow Pipeline Runs

Symptoms: Pipelines take longer than expected.

Optimization Tips:

  1. Use build cache - Enable layer caching for Docker builds
  2. Parallel testing - Run independent tests in parallel
  3. Smaller images - Use Alpine-based images
  4. Shallow clones - Use depth: 1 for source stage
- name: source
  type: source
  config:
    depth: 1 # Shallow clone

UI Loading Slowly

Symptoms: Dashboard takes long to load.

Solutions:

  1. Check your network connection
  2. Clear browser cache
  3. Reduce the number of pipelines shown (use filters)
  4. Check the status page for service issues

Getting More Help

Enable Debug Logging

For more detailed logs, enable debug mode:

settings:
  debug: true

Debug logs include:

  • Detailed command output
  • Environment variable values (secrets masked)
  • Timing information

Collecting Diagnostics

When contacting support, include:

  1. Pipeline ID and Run ID
  2. Stage logs for failing stage
  3. Configuration (redact secrets)
  4. Timestamp of the issue
  5. Error messages (exact text)

Contact Support

If you can’t resolve the issue:

  1. Check the Status Page for outages
  2. Search existing issues on GitHub
  3. Open a new issue with diagnostic info
  4. Email support for urgent issues