常见问题
大多数用户问题都与以下主题有关。 在报告您的问题之前，请检查这些帮助页面中是否已包含解决方案：
在本地构建可以运行，但在 TeamCity 中失败或表现异常
如果在 TeamCity 中构建失败或者行为异常，但您认为不应如此，首先要做的就是检查这个问题是否与 TeamCity 有关。
要做到这一点，请按照以下程序操作：
找到从命令提示符运行任务的方法。 确保它在 TeamCity 代理机器上正常运行，使用与 TeamCity 代理运行相同的用户，以及代理接收的相同环境。 如有必要，以不同用户身份运行 TeamCity 代理，或者调整其环境。
当命令运行正常时，使用 Command Line 运行器在 TeamCity 构建中配置相同的命令，使用自定义脚本设置。
如果那有效，尝试另一个运行器，如果您觉得适用的话。
以下是该方法的详细信息：
请检查在与 TeamCity 代理在同一台机器上，以及在代理运行的同一用户下，使用相同的环境变量和相同的工作目录，相同的架构（32/64 位）命令行时，从命令提示符运行构建是否正常。
如果 TeamCity 构建代理以服务的形式运行（例如，它被安装为 Windows 服务），请尝试以具有管理员权限的常规用户身份从命令行运行 TeamCity 代理 从命令行。 参见 Windows Service 限制。
如果这解决了问题，您可以尝试找出为何在服务下运行会对构建造成问题。 这种情况通常是特定服务的，与 TeamCity 没有直接关联。 另外，您可以设置 TeamCity 代理始终从控制台运行（例如，configure 自动用户登录并在用户登录时运行代理）。
这里是您可以用来从命令行运行构建的详细步骤。
假设您在 TeamCity 中有一个配置了的构建出现失败，那么请按照以下步骤操作：
在 TeamCity 中运行构建并查看其异常行为
禁用该代理，以防止其他构建在其上运行。 这可以在构建仍在进行中时完成
使用与运行 TeamCity 代理的用户相同的用户登录到代理机器（在机器进程列表中检查正确的用户）
停止代理
在命令行控制台中，
cd到问题构建的检出目录（该目录可以在 TeamCity 中构建日志的开头部分查看）。像在开发者的机器上一样，使用命令行运行构建。 这取决于运行器。 （对于一些运行器，您可以在 TeamCity 的构建日志中查看使用的命令行，也可以查看
logs\teamcity-agent.log文件了解 TeamCity 使用的命令行）如果构建失败 —— 应研究原因，因为问题可能与 TeamCity 无关，应在机器上进行调查。
如果运行正常，继续
在同一控制台窗口中，到
cd到<TeamCity agent home>/bin，然后使用agent 启动命令启动 TeamCity 代理。确保 TeamCity 中的 runner 设置适当，并应生成与您手动使用的相同的命令行。 例如，使用 Command Line 构建步骤，选择 Custom script 选项，以及可以保存在
.sh或.bat文件中从命令提示符运行的同一命令。在 TeamCity 中运行构建，并在 Run custom build 对话框中选择代理
完成后，启用 agent
如果从控制台成功构建，但在 TeamCity 中仍然失败，请在 TeamCity 中使用命令行运行器来启动与控制台中相同的命令。
如果在 TeamCity 中仍然表现不同，那么很可能是环境问题或工具问题。
如果命令行运行器能够正常工作，但是在所有选项相同的情况下专用运行器不能正常工作，请在我们的 跟踪器 中创建一个新问题，并详述情况。 请附上所有的构建步骤设置、构建日志、涵盖构建的所有代理日志、您在控制台中用于运行构建的命令，以及构建的完整控制台输出。
在 TeamCity 下构建速度慢
如果您经历了构建速度慢，首先要做的是检查构建日志，看看是否有一些耗时长的操作，或者时间是否在整个过程中分散。 您可以比较较慢和较快构建的构建日志，以找出其中的差异。 您也可以在同一台机器上的控制台运行构建，如上述详细介绍的那样，以查看从控制台运行的构建与在 TeamCity 中的构建是否有任何差别。
如果整个操作过程都很缓慢，那么在构建过程中需要分析代理机器的资源（CPU、硬盘、内存、网络），看看这些中是否存在瓶颈。 Performance Monitor 构建功能可以让您看到构建过程中CPU、内存和硬盘I/O在哪个阶段使用了多少。
如果构建过程出现挂起，那么在正在运行的构建结果页面上的 "查看线程转储" 链接可以帮助理解其发生的原因。
如果存在某个长时间操作，并且它是与 TeamCity 相关的操作（在实际构建过程开始前或结束后），则需要分析 TeamCity 代理和服务器（日志和线程转储）。
如果您想向我们寻求帮助，请确保详细描述问题现象，详细叙述调查过程，并附上构建日志、完整的代理日志和收集到的其他数据。
已启动的 构建代理 在服务器上不可用来运行构建
在安装后或 TeamCity 服务器升级/插件安装后首次启动代理可能需要一些时间，因为代理会从服务器下载更新并进行自动升级。
一般来说，代理应在1到10分钟内完成连接，这取决于代理/服务器网络连接的速度。
如果代理在此期间未能成功连接，请检查代理的名称（如在 conf\buildAgent.properties 文件中配置的那样）并查看 Agents 页面下的标签：
代理正在连接中 —— 代理已准备好运行构建
代理处于已断开连接状态 — 代理曾经连接到服务器，但后来断开了。 在表格中检查 "Inactivity reason" 。 如果原因是 "Agent 已取消注册（将升级）"，那么请再等待几分钟
代理处于未授权状态 — 所有首次连接到服务器的代理都应由服务器管理员进行授权
如果代理程序在状态中停留超过10分钟，并且您与代理程序和服务器之间有快速的网络连接，请执行以下操作：
检查相关的代理机器，以确保代理进程正在运行，且
serverURL中的conf\buildAgent.properties是正确的（并且该机器能够通过该 URL 访问到服务器）；检查所有相关环境 要求 是否已满足；
检查 agent logs（
teamcity-agent.log、launcher.log、upgrade.log）中的任何相关消息 / 错误；检查 服务器日志 (
teamcity-server.log) 是否有任何提及代理名或 IP 的消息/错误。
如果您在日志中找不到延迟升级代理的原因，请联系我们并提供完整的代理和服务器日志。 确保检查 / 包含代理机器上的代理进程（java 进程）的状态。
构建的工件未被清理
如果您遇到在应由服务器清理过程中移除的情况下，工件仍被保存的情况，请检查以下内容：
构建配置的清理规则，工件部分
在构建历史线中，有一个图标表示“此构建被其他构建使用”（位于构建历史的Pin动作/图标之前）
构建"的"依赖项"标签，"已交付制品"部分。 对于每个构建配置，请检查“防止依赖项工件清理”是否已打开（这是默认值）。 如果是这样，那么由于设置的原因，构建的工件没有被清理。
阅读更多关于 清理设置 的信息。
与数据库相关的问题
"内存不足"错误与内部（HSQLDB）数据库相关
如果在启动 TeamCity 服务器时，您遇到像是 "error in script file line: ... out of memory"，"java.sql.SQLException: out of memory" 这样的错误，请执行以下操作：
这是一种尝试手动数据库恢复的方法：
停止 TeamCity 服务器
备份
<TeamCity 数据目录>/system/buildserver.data文件删除
<TeamCity 数据目录>/system/buildserver.data文件，并用同名的零字节文件替换它启动 TeamCity 服务器
然而，如果数据库无法自动恢复，那么手动修复的可能性就非常小了。
内部（HSQL）数据库对于生产使用来说稳定性不足，我们强烈推荐对于 TeamCity 非评估使用采用外部数据库。如果您遇到了数据库损坏，您可以恢复到最后一个完好的备份，或者删除构建历史和用户，但保留设置，详情请参见迁移到外部数据库。
交易...日志已满
此错误可能出现在 MS SQL 或 Sybase 数据库中。 在这种情况下，我们建议增加 TeamCity 数据库的事务日志。 根据系统中构建代理的数量和所有代理每日报告的测试数量，日志大小可以是 1 - 16 GB。
表 'table_name' 已满
这个错误可能会在 MySQL 数据库中出现。 错误信息显示数据库所在的磁盘或临时目录的空闲空间已经用尽。
无法扩展表空间中的...段...
这个错误可能会在 Oracle 数据库中出现。 错误显示，Oracle 无法为表或索引获取更多空间，因为数据库在磁盘上的空间已用完，或者指定的配额不足。
NOCOUNT 已在 MS SQL Server 上启用
teamcity-server.log 报告说，在 MS SQL 数据库服务器上启用了不受支持的 NOCOUNT 选项。 请联系您的 DBA 以禁用该设置。
MySQL JDBC 驱动程序错误：PacketTooBigException
ER_NET_PACKET_TOO_LARGE 错误（PacketTooBigException / 查询的数据包过大）是由于服务器端的 max_allowed_packet 配置变量 设定值过小或保持默认值所导致的。
变量控制了 MySQL 通信缓冲区的最大大小，对于 MySQL 5.6 的 Windows 构建，默认为 4MB，而在流行的 Linux 发行版中（例如。 g. Debian 和 Fedora Core)，此变量默认为 16MB，适用于 i686 和 amd64 两种架构。
数据库字符集/排序规则相关问题
字符集/排序规则不匹配
TeamCity 报告字符集 / 排序不匹配错误：数据库表 / 列的字符集或排序与您的数据库模式中的默认字符集或排序不相同。 如果您的数据库默认使用的是非 Unicode 字符集，您可能会看到此消息，因为 TeamCity 对某些 varchar 字段强制使用 Unicode 字符集。 确保您已根据我们的 建议 配置了数据库。
TeamCity 显示 ???? 而不是国家符号
如果您想要在 TeamCity 中的文本（例如，VCS 消息，测试名称，用户名）中使用本地字符，您需要迁移到具有适当字符集的数据库。
"从备份恢复时出现"唯一键冲突"或"找到重复项"错误
从备份恢复 TeamCity 服务器可能会因为源数据库和目标数据库的字符集（或排序规则）不同并且目标字符集的基数小于源数据库的基数，而导致出现类似于 "唯一键冲突" 或 "找到重复项" 的错误。
为了解决问题，选择并设置正确的字符集（及排序规则）用于目标数据库。
关于大小写敏感性，可能的转换有：
CS > CS
CI > CS
CI > CI
然而，建议您始终使用 CS。
如果源字符集是 Unicode 或 UTF，目标字符集也必须是 Unicode 或 UTF。 如果源字符集是8位非UTF，那么目标字符集可以是同样的或Unicode / UTF。
解决字符集/排序规则相关问题
要解决问题，请执行以下步骤：
创建一个新的数据库，并使用适当的字符集和排序规则。 我们建议使用 unicode 大小写敏感 的排序规则：有关 PostgreSQL 和 MySQL 的说明，请参见。 对于 MySQL，首选
utf8_bin或utf8mb4_bin。
另请参阅 PostgreSQL、MySQL、MS SQL 的文档，了解关于字符集的详细信息。复制当前的
<TeamCity Data Directory>/config/database.properties文件，并将副本中的数据库引用更改为新创建的数据库。停止 TeamCity 服务器。
使用
maintainDB工具迁移到新的数据库：maintainDB migrate [-A <path-to-data-dir>] -T <new-database-properties-file>根据您的数据库大小，迁移可能需要几分钟到几个小时的时间。 有关
maintainDB 工具的更多信息，请参阅 此部分。在成功完成数据库迁移后，
maintainDB工具应该更新<TeamCity Data Directory>/config/database.properties文件，引用新的数据库。 确保该文件已被更新。 如果工具无法自动操作，您需要手动编辑文件。启动 TeamCity 服务器。
MySQL 异常：指定的键太长；最大键长度为 767 字节
索引列大小过大。 最大列大小为 767 字节
检查您的 MySQL 数据库的字符集。 建议使用 utf8 字符集。
如果您的数据库使用 utf8mb4 字符集（自 MySQL 5.5 起可用），请设置以下 InnoDB 配置选项（在 [mysqld] 部分 my.cnf 或 my.ini 中），以运行：
innodb_large_prefix=1允许索引键前缀长度超过 767 字节（最高可达 3072 字节）的 InnoDB 表使用 DYNAMIC 行格式（在 MySQL 5.7.7 中已弃用）。innodb_file_format=Barracuda以启用 DYNAMIC 行格式。innodb_file_per_table=1以启用 Barracuda 文件格式
上述参数具有以下默认值：
MySQL 5.5 | MySQL 5.6 | MySQL 5.7 | MariaDB 5.5 | MariaDB 10.0 | MariaDB 10.1 | MariaDB 10.2 | |
|---|---|---|---|---|---|---|---|
innodb_large_prefix | 0 | 0 | 1 | 0 | 0 | 0 | 1 |
innodb_file_format | 羚羊 | 羚羊 | Barracuda | 羚羊 | 羚羊 | 羚羊 | Barracuda |
innodb_file_per_table | 0 | 1 | 1 | 1 | 1 | 1 | 1 |
根据数据库服务器的版本，需要进行以下配置更改：
MySQL 5.5：
innodb_large_prefix=1innodb_file_format=Barracudainnodb_file_per_table=1
MySQL 5.6 和 MariaDB 从 5.5 到 10.1：
innodb_file_format=Barracudainnodb_file_per_table=1
对于 MySQL 5.7+ 和 MariaDB 10.2+，使用默认设置，无需进行任何更改。
"在 MySQL 中的 'Incorrect string value' 错误
确保数据库使用
utf8mb4字符集和utf8mb4_bin排序规则。 如果情况并非如此，更改 DB 字符集和排序规则。如果字符集和排序规则已经设置正确，但新的错误仍然出现，问题在于 MySQL 中的默认字符集不是 utf8mb4。 将 MySQL 服务器设置为默认使用
utf8mb4，并在my.cnf的[mysqld]部分指定以下选项：
character_set_server = utf8mb4
collation_server = utf8mb4_bin为了使
my.cnf中的更改生效，重启 MySQL。
"'此驱动程序未配置为集成身份验证'错误与 MS SQL 数据库相关
在安装 TeamCity 时，当连接并使用 Windows 集成安全性创建 MS SQL 数据库时，可能会出现以下错误："在执行以下操作时出现 SQL 错误：从数据源获取连接：此驱动程序未配置为集成身份验证。"
问题最常见的原因是 sqljdbc_auth.dll MS SQL 共享库和 TeamCity 使用的 JRE 的位数不同。
为了解决这个问题，请执行以下步骤：
请确保您使用 MS SQL 的原生驱动程序（可以从 Microsoft Download Center 下载）。
使用正确的 JRE 位数：请确保您正在使用与您的
sqljdbc_auth.dllMS SQL 共享库相同位数的 Java 运行 TeamCity。 默认情况下，TeamCity 使用 64 位 Java。 然而，32位和64位的Java版本 都可以使用。
要使用所需的 JRE 运行 TeamCity，请执行以下操作之一： * 设置 TEAMCITY_JRE 环境变量 * 或者从 <TeamCity 安装目录>\jre 中删除与 TeamCity 捆绑的 JRE，并设置 JAVA_HOME。
协议违规错误（仅限 Oracle）
当 Oracle JDBC 驱动程序与 Oracle 服务器不兼容时，可能会出现此错误。 例如，Oracle JDBC 驱动程序版本 11.1 与 Oracle 服务器版本 10.2 不兼容。
为了解决问题，使用您的 Oracle 服务器安装中的 Oracle JDBC 驱动程序，或者下载驱动程序，版本与 Oracle 服务器相同。
常见 Maven 问题
在 TeamCity 构建配置中，通常会看到两种与 Maven 相关的问题：
在构建配置的 "Maven" 标签上出现错误消息："在收集 Maven 项目信息期间出现错误……"
在启动了 Maven 依赖触发器的构建配置中出现错误消息："无法检查 Maven 依赖更新..." 如果构建配置尽管出现此类错误消息，但仍然能够成功构建，那么这些错误可能是由 服务器端 Maven 配置错误 导致的。
为了收集Maven选项卡的信息，或者执行Maven依赖性检查（作为触发器），TeamCity运行嵌入式的Maven。 执行在 服务器 机器上进行，任何 代理端 的 maven 设置都 无法访问。 TeamCity 在服务器端单独解析 settings.xml 文件，如 Maven 服务器端设置 所述。
有必要检查 服务器端的 settings.xml 文件中是否包含关于远程仓库、代理、镜像、配置文件、凭证等的正确信息。
"配置文件中的严重错误"错误
如果您遇到错误，那就意味着存储在 TeamCity 数据目录中的设置处于不一致的状态。 此问题可能在手动更改文件后或者新版的 TeamCity 开始报告不一致性时出现。
为了解决此问题，您可以在服务器文件系统上编辑消息中提到的文件。 在进行任何手动编辑之前，请务必创建文件的备份副本。 通常，服务器重启并非必要才能使更改生效。
带有 id "XXX" 的 VCS 根不存在
构建配置或模板引用了一个在系统中未定义的 VCS 根。 补救措施：恢复 VCS 根目录，或者使用已记录的 id 创建新的 VCS 根目录，或者编辑在消息中提到的文件来删除对 VCS 根目录的引用。
TeamCity 安装问题
如果安装后无法访问 TeamCity 网页用户界面，您可能在一个已被其他程序使用的端口上运行 TeamCity。 检查并配置 您的 TeamCity 安装。
TeamCity NuGet Feed 的问题
如果您在使用部分 TeamCity NuGet Feed 时遇到问题（例如，缺少 NuGet 软件包），您可能需要对 TeamCity NuGet Feed 重新进行索引。
为了强制 TeamCity 对所有可用的包进行重新索引，并重置 NuGet 包列表，请导航至服务器 后台Administration | Diagnostics | 缓存，然后使用 buildsMetadata 重置 链接。
.NET 相关的 TeamCity 工具出现问题
启动性能问题
在 TeamCity 代理上安装的 .NET Framework 低于 4.0 版本可能会因为 Microsoft 强制的代码访问安全性（CAS）政策，导致 .NET 相关的 TeamCity 工具性能问题。
为了解决这个问题，您可以使用以下选项之一：
将以下在 Microsoft 文档 中描述的设置添加到所有代理的
machine.config文件中：<configuration> <runtime> <generatePublisherEvidence enabled="false"/> </runtime> </configuration>您可以按照这篇 外部博客文章 中所述修改 machine.config 文件，并将此配置文件传递给所有代理，例如，使用自定义脚本。
或者，将 TeamCity 代理上的 .NET Framework 升级到 4.0 及以上版本。 详情可在 Microsoft documentation 中查看。
使用需要手动输入的工具，特别是扩展验证代码签名
您可能希望在 TeamCity 代理执行构建过程中，使用一些需要手动交互的工具。 这不是一个特定于 TeamCity 的问题，因此应使用通用方法来处理。
在 Windows 下，您可能希望将 TeamCity 代理 配置为不作为 Service 运行，而是通过配置自动用户登录以访问桌面，相关详情。
扩展验证（EV）代码签名并无简单解决方案，因为该功能是有理由而构建的。 关于这个问题在 stack overflow 上有一些讨论。 合适的解决方案似乎是实施一个拥有自己授权方式的专用服务，并通过它对二进制文件进行签名。
Tomcat 错误：请求头过大
默认情况下，Tomcat 将请求和响应的 HTTP 标头限制为 4096 字节（4KB）。 如果一个头部包含了过多的 cookies （例如，来自于端用户和 TeamCity 之间的代理服务器）或者它们的大小过大，用户可能会在浏览 TeamCity 时遇到 400：请求头过大 或 502：错误的网关 的错误。 为了找出这个问题的原因，我们建议您使用浏览器开发者控制台检查受影响的头部。
为了解决这个问题，通过编辑 $TOMCAT_HOME/conf/server.xml 文件中所有相关连接器的 maxHttpHeaderSize 参数值，增加 Tomcat 头限制。 例如，以下示例将参数值设置为 65536 以将限制提高到 64KB。