# Common Issues (/troubleshooting/common-issues)



Solutions to the most common issues with StarSling Runners.

## Runner Issues

### Personal Repositories Not Supported

**Symptom:** You installed the StarSling GitHub App on a personal repository, but jobs remain queued and are never picked up by StarSling Runners.

**Cause:** StarSling Runners only work with GitHub organizations, not personal repositories.

GitHub's self-hosted runner architecture requires organization-level permissions for secure job routing and runner management. When a workflow runs, GitHub needs to authenticate and route the job to the correct runner pool. This authentication flow relies on organization-level API endpoints and webhook events that aren't available for personal repositories.

Additionally, organization-level runner groups provide security boundaries that allow StarSling to safely manage runners across multiple repositories while maintaining isolation between different customers.

**Solution:** Move your repository to a GitHub organization. You can [create a free organization](https://github.com/account/organizations/new) and transfer your repository to it.

### Runner Not Starting

**Symptom:** Job stays in "Queued" state indefinitely.

**Possible causes:**

1. **GitHub App not installed**
   * Verify the StarSling app is installed on your repository
   * Check Settings → Integrations → GitHub Apps

2. **Invalid label format**
   * Use the correct label format
   * Example: `starsling-ubuntu-24.04`

3. **Quota exceeded**
   * Check if you've hit your account limits
   * Contact support to increase limits

**Solution:**

```yaml
# Correct format
runs-on: starsling-ubuntu-24.04

# Wrong formats
runs-on: starsling-ubuntu-22.04    # ❌ Only Ubuntu 24.04 is supported
runs-on: starsling/ubuntu-24.04    # ❌ Use hyphens, not slashes
runs-on: starsling-ubuntu-latest   # ❌ Use starsling-ubuntu-24.04
```

### Job Fails Immediately

**Symptom:** Job starts but fails within seconds.

**Possible causes:**

1. **Action compatibility issue**
   * Some actions have self-hosted runner restrictions
   * Check action documentation

2. **Missing dependencies**
   * Tool may not be pre-installed
   * Add setup step to install

**Solution:**

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4  # Ensure Node.js is configured
    with:
      node-version: '20'
```

### Slow Performance

**Symptom:** Builds are slower than expected.

**Possible causes:**

1. **Cache misses**
   * Check cache hit rate in logs
   * Verify cache key is correct

2. **Network downloads**
   * Dependencies being downloaded each run
   * Add caching for node\_modules, pip, etc.

3. **Sequential tests**
   * Use matrix builds to parallelize across multiple runners

## Cache Issues

### Cache Not Restoring

**Symptom:** Cache action shows "Cache not found".

**Possible causes:**

1. **Key mismatch**
   * Lockfile changed, generating new key
   * This is expected behavior

2. **Cache expired**
   * Unused caches expire after 7 days
   * Run a fresh build to repopulate

3. **Cross-branch caching**
   * Default branch caches aren't shared to feature branches initially

**Solution:**

```yaml
- uses: actions/cache@v4
  with:
    path: node_modules
    key: deps-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      deps-  # Fallback to partial match
```

### Cache Upload Slow

**Symptom:** Cache upload takes several minutes.

**Possible causes:**

1. **Large cache size**
   * Check what's being cached
   * Exclude unnecessary files

2. **Network issues**
   * Temporary connectivity problems
   * Usually resolves on retry

## Workflow Issues

### Environment Variables Missing

**Symptom:** Expected env vars are undefined.

**Solution:** Ensure you're setting them correctly:

```yaml
jobs:
  build:
    runs-on: starsling-ubuntu-24.04
    env:
      NODE_ENV: production
    steps:
      - run: echo $NODE_ENV
```

<Cards>
  <Card title="Debug Access" href="/troubleshooting/debug-access" description="Get help from support" />

  <Card title="Migration Guide" href="/configuration/migration-guide" description="Ensure correct setup" />
</Cards>