Purpose
You found something wrong with a CleanStart image. Maybe it's a security issue, a runtime error, unexplained behavior, or missing features. This guide explains exactly how to report it effectively, what to expect at each stage, and how to track resolution.
The goal is fast resolution with minimal back-and-forth communication. Providing good information upfront speeds up issue resolution significantly.
Before Reporting: Verification Checklist
Before opening a support case, verify that you've found a genuine CleanStart issue (not application code, configuration, or environment problem):
1. Reproduce on a Clean Environment
Does the issue reproduce consistently?
# Start with a fresh CleanStart imagedocker run --rm registry.cleanstart.com/cleanstart/python:3.12 python --version # If testing an application, isolate it firstdocker run --rm \ -v /path/to/app:/app \ registry.cleanstart.com/cleanstart/python:3.12 \ python /app/test.pyCan you reproduce it every time, or only sometimes? Intermittent issues need more detail.
2. Verify Image Signature and Authenticity
Is this a genuine CleanStart image, or a compromised copy?
# Verify Cosign signaturecosign verify \ --certificate-identity-regexp "https://github.com/cleanstart.*" \ --certificate-oidc-issuer-regexp "https://token.actions.githubusercontent.com" \ registry.cleanstart.com/cleanstart/python:3.12 # Expected output:# Verification successful!If signature verification fails: Do NOT use the image Contact security@clnstrt.dev immediately The image may be compromised.
3. Check Known Issues List
Is this a known issue?
Visit: https://docs.clnstrt.dev/known-issues/Browse issues reported by other users. Frequently reported issues are listed with workarounds.
Look for: Your specific image (python, go, nodejs, etc.) Your version (3.12.1, 1.22, etc.) Symptoms matching your issue.
4. Try Previous Image Version (Regression Test)
Did this issue exist in the previous version?
# Try the previous PATCH versiondocker run --rm registry.cleanstart.com/cleanstart/python:3.12.0 python --version # Try the previous MINOR versiondocker run --rm registry.cleanstart.com/cleanstart/python:3.11 python --versionThis tells us: Is it a regression? (worked before, broken now) Is it a long-standing issue? (broken for months) Does it affect all versions or just one?.
5. Check Documentation for Documented Limitations
Are you hitting a known limitation?
Search: https://docs.clnstrt.dev/Look for: Feature not available in minimal images Known behavioral differences from standard images Configuration required for your use case. example known limitation.
"CleanStart images are shell-less. If your application requires a shell, use a different base image."
How to Report an Issue
Once verified, report the issue. Provide full information—the more details you include, the faster we can help.
Reporting Channels
Choose the appropriate channel for your issue:
Enterprise/Professional Support Tier
Reporting options:1. Support portal: https://support.clnstrt.dev/2. Email: support@clnstrt.dev3. Slack: #support (if enabled)4. Phone: Available 24/7 for critical issues5. Emergency hotline: +1-XXX-XXX-XXXX (P1 only) SLA: Response within 1 hour (P1), 4 hours (P2), 1 day (P3)Community Tier
Reporting options:1. Public issue tracker: https://github.com/cleanstart/images/issues2. Community forum: https://forum.clnstrt.dev/3. Email: community@clnstrt.dev (best-effort response) SLA: None guaranteed, best-effort responseRequired Information (Checklist)
Include all of this in your report:
image identification [ ] Image name and tag (e.g., registry.cleanstart.com/cleanstart/python:3.12.2) [ ] Image digest (SHA256, found with docker inspect) [ ] Signature verification result (passed/failed). environment [ ] Host OS and version (e.g., Ubuntu 22.04 LTS) [ ] Container runtime (Docker 24.0, Podman 4.5, etc.) [ ] Kubernetes version (if applicable: 1.28.5) [ ] Cloud provider (AWS, GCP, Azure, on-premises) [ ] Region/zone (us-east-1, us-central1, etc.). steps to reproduce [ ] Exact commands to reproduce the issue [ ] Input files or data (if applicable) [ ] Application code (minimal reproduction case if possible) [ ] Order of operations (step 1, step 2, step 3...). behavior [ ] Expected behavior (what should happen) [ ] Actual behavior (what actually happened) [ ] Error messages (full error text, not summarized). diagnostic information [ ] Container logs (full output from container startup to error) [ ] System logs (kernel messages, dmesg, journalctl) [ ] Screenshots or terminal output (if visual) [ ] Relevant configuration files (Dockerfile, docker-compose.yml, etc.).
Example Issue Report: Good
Title: Python 3.12 fails to import numpy on RHEL 9 Image: registry.cleanstart.com/cleanstart/python:3.12.1Digest: sha256:abc123def456789...Host OS: RHEL 9.1 (kernel 5.14.0-284.el9.x86_64)Container Runtime: Docker 24.0.5 Steps to reproduce:1. Run: docker run registry.cleanstart.com/cleanstart/python:3.12.1 python -c "import numpy; print(numpy.__version__)"2. Container exits with error Expected: numpy imports successfully and prints versionActual: ImportError: /lib64/libc.so.6: version `GLIBC_2.36' not found Error messages:Error: /lib64/libc.so.6: version `GLIBC_2.36' not found (required by /usr/local/lib/python3.12/site-packages/numpy.so) Container logs:[full container startup logs here] Reproduced on:- Python 3.11.5 (works fine)- Python 3.12.0 (fails, same error)- Python 3.12.1 (fails, same error) Dockerfile:FROM registry.cleanstart.com/cleanstart/python:3.12.1RUN pip install numpy==1.24.3 Docker-compose.yml:[relevant config]Example Issue Report: Poor
Title: Python doesn't work Image: pythonError: Something went wrong Steps: Run docker and it breaksExpected: Should workActual: It doesn't [no logs, no version info, no reproduction case]Optional But Helpful Information
Include if available:
system information Output of: docker info Output of: docker version Output of: uname -a. sbom information Relevant packages from image SBOM Specific vulnerable package version (if security issue). performance data CPU, memory, disk usage (if performance issue) Before/after comparison to previous version Load testing results (if load-related). business impact How many users/services affected Workaround status (is there a workaround?) Revenue impact (critical path vs. non-critical).
Issue Lifecycle
Every issue progresses through defined states. Understanding these helps you track progress.
Issue States
A defect begins as NEW, then proceeds to TRIAGED. From triage, it moves to IN PROGRESS, then to FIX READY. Once fixed, it moves to VERIFIED and finally CLOSED. Alternatively, if a defect is determined to be invalid, it may be marked as WON'T FIX, DUPLICATE, or NOT A BUG, after which it is CLOSED.
State Descriptions
NEW
what it means: Issue received but not yet reviewed.
what to expect Acknowledgment with ticket number (within 1 hour for Enterprise, 24 hours for Community) Likely automated response or human acknowledgment No analysis yet. what you should do Nothing (unless asked for more info) Issue is queued for triage.
TRIAGED
what it means: Issue reviewed, severity assigned, timeline estimated.
what to expect Priority assigned (P1/P2/P3/P4) Initial assessment provided Estimated timeline for next step May request additional information. what you should do Respond to requests for information promptly Confirm if priority assessment makes sense Confirm reproducibility. example triage response.
PRIORITY: P2 (High)SEVERITY: Regression in 3.12.1, worked in 3.12.0 ASSESSMENT:This appears to be a library version incompatibility. The GLIBCrequirement changed between versions. This affects numpy userson RHEL 9 specifically. ESTIMATED TIMELINE: Fix in next patch (3.12.2), ~7 days NEXT STEP: Engineer assigned, investigation begins tomorrowIN PROGRESS
what it means: Engineer assigned, actively working on the issue.
what to expect Engineer name assigned May ask clarifying questions May request additional diagnostic data May share intermediate findings May provide workaround if available. what you should do Respond to engineer questions Provide any additional information requested Test workarounds if offered. example in-progress communication.
ENGINEER: Alice ChenSTATUS: Investigating root cause FINDINGS SO FAR:- Confirmed: Issue is numpy <-> GLIBC 2.36 incompatibility- Confirmed: Affects Python 3.12+ on RHEL 9- Not affects: Debian, Ubuntu, Alpine- Workaround: Use Python 3.11.x or pin numpy < 1.24 QUESTIONS:1. Are you pinning numpy version in your Dockerfile?2. Can you test with Python 3.11 to confirm workaround? NEXT: Will coordinate with CleanStart maintainers about GLIBC version policyFIX READY
what it means: Fix developed, tested, ready for you to validate.
what to expect New image version published (e.g., python:3.12.2) You're notified and provided with link Instructions for testing the fix Expected to validate and report success/failure. what you should do.
- Pull the new image
- Test with your application
- Confirm fix works or report if it doesn't
- Move issue to VERIFIED (if works) or back to IN PROGRESS (if doesn't)
example notification.
FIX READY: python:3.12.2 Patched GLIBC version to 2.38, resolving numpy compatibility issue. Available: registry.cleanstart.com/cleanstart/python:3.12.2Signature: Verified with Cosign PLEASE TEST:1. docker pull registry.cleanstart.com/cleanstart/python:3.12.22. Rebuild your image3. Test numpy import: python -c "import numpy; print(numpy.__version__)"4. Report success or failure TARGET ISSUE CLOSURE: Once you confirm fix worksVERIFIED
what it means: You confirmed the fix works, issue is resolved.
what to expect Issue marked as VERIFIED Optional: included in release notes Optional: case study/blog post (if interesting) Case closed. what you should do No action required Issue is closed Update your deployment to new version when ready.
CLOSED
what it means: Issue is resolved and closed.
Reasons for closure: VERIFIED: Fix deployed and working DUPLICATE: Same as another issue (linked to primary issue) WON'T FIX: Won't be addressed (explained why) NOT A BUG: Not actually a CleanStart issue (explained why).
SLA: Response and Resolution Times
By Priority
Priority | Severity | Impact | Triage | First Response | Resolution Target | Examples |
|---|---|---|---|---|---|---|
P1 | Critical | Production down | 1 hour | 1 hour | 24 hours | CVE in running image, complete image failure |
P2 | High | Production degraded | 4 hours | 4 hours | 7 days | Noticeable latency/memory issue, security concern |
P3 | Medium | Minor impact | 1 business day | 1 business day | 30 days | Feature doesn't work, performance regression |
P4 | Low | No immediate impact | 3 business days | 3 business days | Next release | Documentation issue, minor aesthetic problem |
What Each SLA Means
triage: Time from issue creation to priority assignment first response: Time from issue creation to engineer first communication resolution target: Time from issue creation to fix available (not deployment).
important: SLAs apply to Enterprise/Professional support. Community tier is best-effort.
SLA Example
Example timeline for a critical CVE issue:
Tuesday 14:00 UTC: Issue reported (P1 - Critical CVE) Tuesday 14:30 UTC: Triaged within 1 hour SLA - P1 assigned Tuesday 15:00 UTC: First response within 1 hour SLA - Engineer Bob assigned, investigating Tuesday 15:30 UTC: Finding documented - CVE in glibc identified, fix needed Wednesday 09:00 UTC: Fix ready within 24 hour SLA - New image python:3.12.5 available Wednesday 10:00 UTC: Customer confirms fix is verified Wednesday 11:00 UTC: Issue closed
Escalation Process
If an issue isn't progressing as expected:
Escalation Criteria
Escalate if: P1: No acknowledgment within 1 hour P2: Not triaged within 4 hours P3: Not triaged within 1 business day Any: Exceeds resolution target by 50% or more Any: Customer has requested escalation.
How to Escalate
email: escalations@clnstrt.dev subject: ESCALATION: [TICKET-123] [PRIORITY] content Ticket number Current status Why you're escalating Impact/urgency. example.
To: escalations@clnstrt.devSubject: ESCALATION: TICKET-12345 [P2] This issue was opened 48 hours ago and still isn't triaged. TICKET: TICKET-12345PRIORITY: P2 (High - production latency)ISSUE: Memory leak in Python 3.12.1IMPACT: Our service using 10x normal memory, risk of OOM Expected triage: 4 hoursActual: 48 hours (12x SLA) Please prioritize this for immediate triage.response: Escalation team reviews and escalates within 1 hour (business hours).
Workarounds While Waiting for Fix
If a fix isn't available immediately, we'll try to provide a workaround.
Workaround Types
built-in: Use a feature or configuration to avoid the issue.
# Example: If issue is with specific feature, disable itdocker run \ -e FEATURE_X_ENABLED=false \ registry.cleanstart.com/cleanstart/python:3.12.1 \ python /app/main.pyversion downgrade: Use previous version until fix available.
# If python:3.12.1 is broken, use 3.12.0docker build --build-arg BASE=registry.cleanstart.com/cleanstart/python:3.12.0 .custom image: Use cleanimg-customize v0.3.0 to build a workaround image.
cat > workaround-spec.yaml <<EOFbase_image: "registry.cleanstart.com/cleanstart/python:3.12.1"arch: amd64variant: prodpackages: - name: glibc version: "2.39-r1"cleanstart_repos: trueEOFcleanimg-customize build --spec workaround-spec.yaml --tag myregistry.com/python:3.12.1-patched --pushnetwork configuration: Adjust your environment temporarily.
# If issue is network-related, configure differentlydocker run \ --net=host \ registry.cleanstart.com/cleanstart/python:3.12.1 \ python /app/main.pymonitoring adjustment: Monitor more closely for impact.
# Alert if the issue symptom appears# Temporarily lower thresholds while investigatingAfter Issue Resolution
Post-Incident Tasks
Once your issue is resolved:
- Update your deployment to new fixed version
- Test in staging before production rollout
- Provide feedback on fix (did it really solve your problem?)
- Participate in case study (optional, helps community)
- Update monitoring if you added temporary alerts
Feedback on Fix
Reply to the VERIFIED notification with:- Confirmation that fix works- Any side effects observed- How long it took to deploy- Impact on your operations- Thank you! (helps the team know their effort is appreciated)Common Issue Categories and Solutions
Performance Issues (Memory, CPU)
before reporting [ ] Baseline: What's normal CPU/memory for your app? [ ] Increase: Is memory/CPU growing or constant high? [ ] Timing: When does it happen? Startup? After 1 hour? Load-dependent? [ ] Reproducible: Can you trigger it, or random?. information to include.
# Capture resource usagedocker stats --no-stream # Check what processes are consuming resourcesdocker exec <container> top -b -n 1 | head -20 # Check for leaks (memory growing over time)docker exec <container> ps aux # Heap dump (if Java/Python app)jmap -heap <pid> # Javatracemalloc # PythonSecurity Issues
before reporting [ ] Check if CVE is publicly known [ ] Verify with: syft registry.cleanstart.com/cleanstart/python:3.12 [ ] Check SBOM for affected package version. report to security@clnstrt.dev (private security report) GPG key: https://clnstrt.dev/security.gpg. example.
To: security@clnstrt.dev SECURITY ISSUE: CVE-2024-XXXXX in glibc AFFECTED IMAGE: registry.cleanstart.com/cleanstart/python:3.12.1PACKAGE: glibc 2.37CVE: CVE-2024-XXXXXCVSS SCORE: 9.8 (Critical) This CVE affects [your use case]. We discovered this duringsecurity scanning and need immediate patch. TIMELINE: Ready to deploy on 2025-03-24Compatibility Issues (Language, Libraries)
before reporting [ ] Test with application code on CleanStart image [ ] Compare against standard image (Alpine, Ubuntu) [ ] Check if it's documented limitation [ ] Verify package versions in SBOM. information to include.
# Show what's differentdocker run registry.cleanstart.com/cleanstart/python:3.12 python -c "import sys; print(sys.version)"docker run ubuntu:22.04 python3 --version # Show dependency differencesdocker run registry.cleanstart.com/cleanstart/python:3.12 pip freeze > cleanstart.txtdocker run ubuntu:22.04 pip3 freeze > ubuntu.txtdiff cleanstart.txt ubuntu.txtIssue Tracking and Status
How to Track Your Issue
enterprise/professional Support portal dashboard Email notifications at each state change Slack integration (if enabled). community GitHub issues: https://github.com/cleanstart/images/issues/[NUMBER] Watch the issue for updates Subscribe to comments.
Example Status Update
⏱️ ISSUE OPEN FOR 3 DAYS TICKET: TICKET-54321STATUS: In ProgressPRIORITY: P2 TIMELINE SO FAR:- 2025-03-23 14:00: Issue reported- 2025-03-23 14:15: Triaged as P2- 2025-03-23 15:00: Engineer assigned (Alice Chen)- 2025-03-24 09:00: Root cause identified- 2025-03-24 14:00: Fix in development- 2025-03-25 10:00: Fix testing in progress NEXT STEP: Fix should be ready within 24 hours STATUS PAGE: https://support.clnstrt.dev/tickets/TICKET-54321What to Read Next
08-reference/api-cli/api-compatibility-policy.md: Understanding version support and deprecation timelines 06-operate/observability/alerting-playbooks.md: Setting up alerts to catch issues before they become critical 08-reference/deployment/container-image-security.md: Security best practices for verifying CleanStart images.