Troubleshooting

This guide helps diagnose and resolve common issues with CloudRepo.

Quick Diagnostics

Before diving into specific issues, run these quick checks:

Connection Test

# Test basic connectivity (any response — including 401 — proves you reached us)
curl -I https://[org-id].mycloudrepo.io

# Test your repository credentials. This is the ONLY command here that
# distinguishes good credentials from bad, because authentication is checked
# before the repository is looked up:
#   401 -> the credentials were REJECTED
#   404 -> credentials accepted; the repository name is wrong
#   403 -> credentials accepted; this user has no access to that repository
#   200 -> credentials accepted and the repository is readable
curl -u username:password https://[org-id].mycloudrepo.io/repositories/[repo-name]/

Network Diagnostics

# DNS resolution
nslookup [org-id].mycloudrepo.io

# Trace network path
traceroute [org-id].mycloudrepo.io

# Check SSL certificate
openssl s_client -connect [org-id].mycloudrepo.io:443

Authentication Issues

401 Unauthorized

Symptoms: * “401 Unauthorized” errors * “Authentication failed” messages

Common Causes & Solutions:

Incorrect credentials:
```
# Test credentials directly, against a repository you expect to be able to read.
# Authentication runs before the repository lookup, so a 404 or 403 here still
# means the credentials were ACCEPTED — only a 401 means they were rejected.
curl -o /dev/null -w '%{http_code}\n' \
     -u username:password \
     https://[org-id].mycloudrepo.io/repositories/[repo-name]/
```
Warning

Do not test credentials against a path your repository host does not serve. [org-id].mycloudrepo.io serves only /repositories/... paths, and it answers 401 for every path it does not recognise, so an unrecognised path returns 401 whether your credentials are valid or not. Testing against one will make good credentials look broken and lead you to rotate a working credential.
Special characters in password:
- URL-encode special characters
- Use %40 for @, %23 for #, etc.

403 Forbidden

Symptoms: * “403 Forbidden” errors * “Access denied” messages

Solutions:

Check repository permissions: * Verify user has access to repository * Confirm read/write permissions
IP restrictions: * IP blocking is configured by CloudRepo support, not in the portal * Contact support@cloudrepo.io to check whether a range applies to you

Repository Access Problems

404 Not Found

Common Causes:

Incorrect repository URL:

❌ Wrong: https://[org-id].mycloudrepo.io/maven-releases
✅ Right: https://[org-id].mycloudrepo.io/repositories/maven-releases

Repository doesn’t exist: * Verify repository name * Check repository was created

Python simple index:

❌ Wrong: https://[org-id].mycloudrepo.io/repositories/pypi
✅ Right: https://[org-id].mycloudrepo.io/repositories/pypi/simple

Artifact Not Found

Debugging Steps:

Verify artifact was uploaded:

curl -u username:password \
  https://[org-id].mycloudrepo.io/repositories/[repo-name]/[path]

Check artifact path: * Maven: com/example/artifact/1.0/artifact-1.0.jar * Python: Check package name matches
Repository type mismatch: * Ensure uploading to correct repository type * Releases vs. snapshots for Maven

Upload/Download Issues

Slow Performance

Diagnosis:

# Test download speed
time curl -o /dev/null \
  https://[org-id].mycloudrepo.io/repositories/[repo]/test-file

Solutions:

Network optimization: * Check internet bandwidth * Use CloudRepo CDN endpoints * Configure connection pooling

Client configuration:

Maven - Increase threads

<configuration>
  <maxThreads>10</maxThreads>
</configuration>

Use proxy repositories: * Cache external dependencies * Reduce external downloads

Upload Failures

Large File Uploads:

# Use chunked transfer for large files
curl -u username:password \
  --upload-file large-file.zip \
  --header "Transfer-Encoding: chunked" \
  https://[org-id].mycloudrepo.io/repositories/raw/large-file.zip

Timeout Issues:

Increase client timeout settings
Use resumable uploads for very large files
Consider splitting into smaller artifacts

SSL/TLS Problems

Certificate Errors

Symptoms: * “SSL certificate problem” * “unable to verify the first certificate”

Solutions:

Update CA certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# CentOS/RHEL
sudo yum install ca-certificates

# macOS
brew install ca-certificates

Java applications:

# CloudRepo's certificate on *.mycloudrepo.io is publicly trusted and needs no
# import. On a custom domain, import the CA that issued your certificate.
# Import your corporate proxy's CA if your network terminates TLS at one.
# Resolve the truststore BEFORE importing. Two things bite here:
#   * Java 8 keeps it at $JAVA_HOME/jre/lib/security/cacerts, Java 9+ at lib/security.
#   * keytool CREATES the file if the path is wrong, prints "Certificate was added to
#     keystore" and exits 0 -- so a wrong path is a silent no-op wearing a success
#     message, and a `keytool -list` against that same wrong path agrees with it.
CACERTS="$JAVA_HOME/lib/security/cacerts"
[ -f "$CACERTS" ] || CACERTS="$JAVA_HOME/jre/lib/security/cacerts"
[ -f "$CACERTS" ] || { echo "No cacerts under $JAVA_HOME - is it the JDK your build uses?"; exit 1; }

keytool -importcert -keystore "$CACERTS" -storepass changeit -noprompt \
  -alias corporate-proxy-ca -file corporate-ca.crt

# Verify against the RESOLVED path, not an asserted one.
keytool -list -keystore "$CACERTS" -storepass changeit -alias corporate-proxy-ca

Python applications:

# Update certifi
pip install --upgrade certifi

# Behind a TLS-inspecting corporate proxy, trust its CA --
# do not disable verification.
#
# Try first with nothing set: pip 24.2+ on Python 3.10+ reads the OS trust
# store on its own. If you must name a file, use your distribution's path --
# Debian/Ubuntu /etc/ssl/certs/ca-certificates.crt, RHEL/Rocky/Alma
# /etc/pki/tls/certs/ca-bundle.crt -- a wrong path fails hard.
pip config set global.cert /etc/ssl/certs/ca-certificates.crt

# Otherwise build a bundle. Whether `cert` REPLACES the trust store depends on
# Python: below 3.10 (and on pip 24.1 and earlier) it replaces outright, so a
# corporate-CA-only file breaks installs from pypi.org. A concatenated bundle
# is right in every combination.
# The `&&` is the guard: without it `>` truncates the bundle to the corporate
# CA alone when certifi is missing, and the failure is not visible.
CERTIFI_PEM="$(python3 -m certifi)" && \
  cat "$CERTIFI_PEM" /path/to/corporate-ca.crt > /path/to/corporate-bundle.pem
pip config set global.cert /path/to/corporate-bundle.pem

Build Tool Specific Issues

Maven

Metadata Issues:

# Force metadata update
mvn -U clean install

# Clear local repository cache
rm -rf ~/.m2/repository/com/example/your-artifact

Settings.xml Problems:

# Validate settings.xml
mvn help:effective-settings

# Use specific settings file
mvn -s /path/to/settings.xml deploy

Gradle

Cache Issues:

# Clear Gradle cache
gradle clean build --refresh-dependencies

# Remove specific cached artifact
rm -rf ~/.gradle/caches/modules-2/files-2.1/com.example

Configuration Problems:

// Enable debug logging
gradle.startParameter.showStacktrace = ShowStacktrace.ALWAYS
gradle.startParameter.logLevel = LogLevel.DEBUG

Python/pip

Index Issues:

# Clear pip cache
pip cache purge

# Force reinstall
pip install --force-reinstall --no-cache-dir package-name

Configuration Problems:

# Check current configuration
pip config list

# Set repository URL
pip config set global.index-url https://[org-id].mycloudrepo.io/repositories/pypi/simple

CI/CD Integration Issues

Environment Variables

Debugging:

# Print environment (mask passwords!)
env | grep CLOUDREPO | sed 's/PASSWORD=.*/PASSWORD=***/'

Common Issues:

Variables not exported
Incorrect variable names
Special characters not escaped

Secret Management

GitHub Actions:

# Debug secrets (safely)
- name: Check secrets
  run: |
    if [ -z "${{ secrets.CLOUDREPO_USERNAME }}" ]; then
      echo "Username secret not set"
    else
      echo "Username secret is configured"
    fi

Jenkins:

// Verify credentials exist
withCredentials([usernamePassword(
  credentialsId: 'cloudrepo-creds',
  usernameVariable: 'USER',
  passwordVariable: 'PASS'
)]) {
  sh 'echo "Credentials loaded successfully"'
}

Common Error Messages

“Connection refused”

Causes: * Firewall blocking connection * Proxy configuration needed * CloudRepo service issue (check status.cloudrepo.io)

“Checksum validation failed”

Solutions: * Re-upload artifact * Clear local cache * Verify network stability

“Repository is read-only”

Causes: * User lacks write permission * Repository configured as read-only * Quota exceeded

Performance Diagnostics

Measuring Performance

Performance test script

import time
import requests

def test_performance(url, auth):
    times = []
    for i in range(10):
        start = time.time()
        response = requests.get(url, auth=auth)
        elapsed = time.time() - start
        times.append(elapsed)
        print(f"Request {i+1}: {elapsed:.2f}s")

    avg = sum(times) / len(times)
    print(f"Average: {avg:.2f}s")

# Run test
test_performance(
    "https://[org-id].mycloudrepo.io/repositories/maven-releases/test.jar",
    ("username", "password")
)

Debug Logging

Enable Verbose Logging

Maven:

mvn -X deploy

Gradle:

gradle --debug publish

pip:

pip install -v package-name

curl:

curl -v -u username:password https://[org-id].mycloudrepo.io/repositories/[repo-name]/

Analyzing Logs

Look for: * HTTP status codes * Response headers * Error messages * Timing information

Getting Help

Self-Service Resources

Check CloudRepo status: https://status.cloudrepo.io
Review documentation: This guide
Search knowledge base: Knowledge Base

Contacting Support

When contacting support, provide:

Organization ID
Repository name
Error messages (full text)
Steps to reproduce
Debug logs (if available)
Time of occurrence

Email: support@cloudrepo.io Response time: Usually within 2 business hours

Emergency Issues

For critical production issues: * Mark email as “URGENT” * Include business impact * Provide contact phone number

Next Steps

Still Need Help? - FAQs and common issues
Repository Management - Repository configuration
Continuous Integration and Deployment - CI/CD setup
Contact support@cloudrepo.io for unresolved issues