Diagnosing Travis CI Build Hangs and Failures Due to Environment, Cache, Resources, or SSH Key Issues

Recognizable Condition

Travis CI builds can exhibit one of several observable symptoms that point to a specific class of misconfiguration:

• The job hangs indefinitely at the "Setting up environment variables" step.
• The build fails with a message like "Failed to cache directories" or similar cache‑related errors.
• Tests exceed the default 50‑minute timeout and are killed by Travis.
• The deployment step aborts with "Permission denied (publickey)" when attempting to use an SSH deploy key.

Cause/Diagnostic Table

Observed Condition	Likely Cause	What to Look For in the Log
Stalls at environment variable setup	Missing or malformed secure environment variables (encrypted values that cannot be decrypted)	The log shows the step pausing with no further output; subsequent steps never start.
"Failed to cache directories" error	Cache paths do not exist, are not writable, or are incorrectly specified	After the cache step, Travis reports an error and continues without caching; the directory listed in cache: is absent or empty.
Test timeout after 50 minutes	Insufficient CPU/memory allocation or an infinite loop in the test suite	The log shows the test runner running for close to 50 minutes, then a message like "Job was killed because it exceeded the maximum allowed time".
"Permission denied (publickey)" on SSH deploy	Deploy key not added to the repository or SSH agent not loaded	The deployment command outputs "Permission denied (publickey)" and the build fails; no successful SSH handshake appears.

Ordered Checks

1. Verify environment variables
   • Add a script step early in .travis.yml that echoes the variable (use single quotes to avoid accidental expansion):

     script:
       - echo '$MY_VAR'

   • Run the build; check the log for the echoed value. If the line is blank or shows the literal string $MY_VAR, the variable is not set.
   • Risk: Echoing secrets exposes them in the log; only test with non‑sensitive placeholders.
2. Verify cache directory
   • Insert a step before and after the cache directive to list the target directory:

     before_cache:
       - ls -la $HOME/cache
     cache:
       directories:
         - $HOME/cache
     after_cache:
       - ls -la $HOME/cache

   • Run the build and compare the two listings. If the directory is missing or empty after the cache step, the path is incorrect or not writable.
   • Risk: Misconfigured cache can cause silent misses, lengthening build times without obvious errors.
3. Verify resource limits
   • Add a step that reports CPU and memory usage (available in the Travis VM via /proc/meminfo and /proc/cpuinfo):

     script:
       - cat /proc/meminfo | grep MemTotal
       - nproc

   • If the values are far below what your test suite expects (e.g., < 2 GB RAM or < 2 CPU cores), consider reducing parallelism or optimizing the test suite.
   • Risk: Reducing concurrency may increase build time; ensure tests remain reliable.
4. Verify SSH deploy key
   • Add a step that attempts an SSH connection to GitHub (or your Git server) without triggering a password prompt:

     script:
       - ssh -T [contact removed]

   • Run the build. Success is indicated by a message like "Hi username! You've successfully authenticated..." . Failure shows "Permission denied (publickey)".
   • Risk: If the key is missing, the step will hang waiting for input; ensure BatchMode yes is implied by -T.

Fixes Tied to Findings

• Environment variable missing/malformed
  • Ensure the variable is defined in the repository settings under "Settings → Environment Variables" and that the "Display value in build log" toggle is OFF for secrets.
  • If using the Travis CLI to encrypt a value, verify the encrypted string matches the one in .travis.yml (e.g., secure: "…").
  • Re‑encrypt the value with the current Travis CLI version if you suspect corruption.
• Cache path issues
  • Correct the cache: section to point to an existing, writable directory (commonly under $HOME).
  • Create the directory in a before_install step if it may not exist: mkdir -p $HOME/cache.
  • Ensure the user running the build (typically travis) has write permissions; avoid sudo unless absolutely necessary, as newer Trusty images may restrict it.
• Insufficient resources
  • Reduce parallel test jobs (e.g., change make -j4 to make -j2) or split the test matrix into smaller chunks.
  • Consider moving to a newer Travis image with larger default resources if your plan supports it.
  • Optimize the test suite to avoid infinite loops or excessively long setup steps.
• SSH deploy key problems
  • Generate a deploy key pair (if not already done) and add the public key to the repository’s "Deploy keys" section, granting write access if needed.
  • Add the private key to Travis CI settings as an environment variable (e.g., SSH_DEPLOY_KEY) and ensure it is loaded in the build:

    before_install:
      - mkdir -p ~/.ssh
      - echo "$SSH_DEPLOY_KEY" > ~/.ssh/id_rsa
      - chmod 600 ~/.ssh/id_rsa
      - ssh-keyscan github.com >> ~/.ssh/known_hosts

  • Verify the key works with the SSH test step described above.

Escalation Criteria

• If after applying the above fixes the build still hangs at the environment variable step, contact Travis CI support with the full log and confirm that the repository’s encryption key has not been rotated.
• Persistent cache failures despite correct paths may indicate a VM‑level issue (e.g., disk space exhaustion); request a clean VM or consider disabling caching temporarily to isolate the problem.
• Repeated timeouts after reducing parallelism suggest a deeper problem in the test suite (e.g., deadlock) that may require external profiling; consider running the suite locally with resource limits to reproduce.
• If SSH authentication continues to fail after confirming the key is present and the agent is loaded, verify that the repository does not have deploy key restrictions or that the key is not also used as a user key elsewhere causing a conflict.