---
title: "SourceDeploy troubleshooting"
slug: "sourcedeploy-troubleshoot"
updated: 2026-09-17T09:18:20Z
published: 2026-09-17T09:18:20Z
canonical: "guide.ncloud-docs.com/sourcedeploy-troubleshoot"
stale: true
---
> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SourceDeploy troubleshooting
Available in Classic and VPC
You might run into the following problems when using SourceDeploy. Find out causes and possible solutions.
## Agent connection error
When I execute deployment while the agent for SourceDeploy is installed, the "Agent connection fail" log occurs. I received the message "Failed to connect agent."
#### Cause
- An error may occur when the NCP_AUTH_KEY file does not exist.
- An error may occur when your Python version is not supported.
- An error may occur when an incorrect agent version is used.
- An error may occur when you install an agent that does not work with your environment.
#### Solution
- **When the NCP_AUTH_KEY does not exist**
- The NCP_AUTH_KEY file should exist under the server's /opt directory in order for the agent to operate properly.
- Check if the key file exists.
- Check if the content of the key file was written correctly.
- To learn how to write an NCP_AUTH_KEY file, see [Install and manage agent](/docs/en/devtools-devtools-4-4).
- **When your Python version is not supported**
- The agent operates in Python 3.6 or higher and 3.12.7 or lower, based on the Korean Region. Check the Python version installed on the server.
- **When an improper agent was installed for your environment**
- See [Install and manage agent](/docs/en/devtools-devtools-4-4) to check supported specifications, and enter the download address for the agent that works with your Region and environment.
- **When the agent is in an older version**
- Enter the agent status check commands and check if the agent has been installed normally.
```
service sourcedeploy status
```
- Check the installed version of the agent.
```
cat /opt/sdagent/Agent.ver
```
Example: As of May 27, 2021.
```
[VERSION]
ver=2021/05/18/01
```
- If the agent installed is an older version, then delete and reinstall the agent.
- See [Delete agent](/docs/en/devtools-devtools-4-4#%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EC%82%AD%EC%A0%9C) for more information on deleting agent.
- Check if the server status is **Running**.
- If the agent error continues after conducting the aforementioned items, forward the operation logs to [Customer Support](https://www.ncloud.com/support/question/service).
To view agent operation logs, follow these steps:
```
$ grep gateway /opt/sdagent/resource.py;
$ service sourcedeploy status;
$ cat /opt/sdagent/Agent.ver;
$ cat /var/sourcedeploy/log/sourcedeploy-0-system.log
```
## Agent process execution error
The agent process does not run normally.
#### Cause
The agent is not installed normally.
#### Solution
- Enter the restart commands to restart the agent.
```
service sourcedeploy restart
```
- Install the following Linux packages and reinstall the agent if the agent does not operate normally even after restarting.
```
# CentOS, Rocky
sudo yum install -y epel-release ca-certificates openssl-devel zlib-devel
# Ubuntu
sudo apt-get install -y build-essential ca-certificates libssl-dev zlib1g-dev
```
- You can check the agent process to view if the agent is running normally.
```
ps -ef | grep main.py
```
Note
The normal run criteria for the agent process are as follows:
- Run 1 process.
## Agent installation error
The agent is not installed properly.
#### Cause
- The authentication key value is entered incorrectly.
- The script directory is specified incorrectly.
- The agent installation URL is entered incorrectly.
#### Solution
- Check if the correct authentication key value has been entered.
```
cat /opt/NCP_AUTH_KEY
```
- Check if the directory of the script you want to run is specified in the form of `#!/usr/bin/env python`, `#!/bin/perl`, or `#!/bin/bash` in the first line of the Init Script.
- Check if the following agent installation URL is entered in the Init Script. `Shell wget {Agent download address}`
| Environment | Region | Agent download address | Header name | Header value |
| --- | --- | --- | --- | --- |
| VPC | Korea (KR) | https://sourcedeploy-agent.apigw.ntruss.com/agent/vpc-v2/download/install | x-ncp-region_code | KR |
| Singapore (SGN) | SGN |
| Japan (JPN) | JPN |
| Classic | Korea (KR) | https://sourcedeploy-agent.apigw.ntruss.com/agent/v3/download/install | - | - |
- The following are the addresses to download the agent for each environmental requirement and Region:
Note
If the `x-ncp-region_code` header is not set, "KR" is applied by default.
## Python installation failure
It fails in the Python installation step.
#### Cause
SourceDeploy's agent uses Python 3.6 or higher and 3.12.7 or lower. A problem may occur if the Python was not installed automatically via the Agent Install script.
#### Solution
Run the following command to install Python3.
```
$ apt-get install -y python3.11
```
## Rollback failure
Failed to rollback.
#### Cause
- The previously deployed files do not exist in Object Storage.
- The last successful deployment record does not exist.
- Files have been changed.
#### Solution
SourceDeploy's rollback feature operates in a way to rerun the last successful deployment. Check if there is last successful deployment record and the deployment file exists in Object Storage.
## Learning resources
We offer various materials for you to explore. To learn more about SourceDeploy, check out these helpful links:
- FAQs: [Frequently asked questions from SourceDeploy users](https://www.ncloud.com/support/faq/prod?categoryCode2=DEVTL&categoryCode3=SV_0106&page=1)
- NAVER Cloud Platform blog: [SourceDeploy & SourceBuild - provides Github Enterprise Server integration feature](https://blog.naver.com/n_cloudplatform/223272473873?trackingCode=blog_bloghome_searchlist)
- NAVER Cloud Platform blog: [Deploy applications to Kubernetes clusters - Practice using NAVER Cloud Platform's Developer Tools](https://blog.naver.com/n_cloudplatform/223209131446?trackingCode=blog_bloghome_searchlist)
- API guides: [SourceDeploy API guide](https://api.ncloud-docs.com/docs/en/devtools-sourcedeploy)