Document accepted kill_timeout formats in fly.toml reference

reference/configuration.html.markerb

@@ -30,13 +30,13 @@
 
 ## The `app` name
 
 The first key/value in any `fly.toml` file is the application name. This will also be used to create the host name that the application will use by default. For example:
 
 ```toml
 app = "restless-fire-6276"
 ```
 
 Whenever `flyctl` is run, it will look for a `fly.toml` file in the current directory and use the application name in that file. This behavior can be overridden by using the `-a` flag to set the application name, or on some commands (such as `deploy`) by using a `-c` flag to point to a different `fly.toml` file.
 
 ## Primary region
 
@@ -48,13 +48,13 @@
 
 ## Runtime options
 
 The following options are available to control the lifecycle of a running application. These are optional and can be placed at the top level of the `fly.toml` file:
 
 ### `kill_signal` option
 
 When shutting down a Fly Machine, Fly.io sends a `SIGINT` signal to the running process by default. Typically this triggers a hard shutdown option on most applications. The `kill_signal` option lets you override that with a different signal so that you can trigger a softer, less disruptive shutdown: `SIGTERM`, `SIGQUIT`, `SIGUSR1`, `SIGUSR2`, `SIGKILL`, or `SIGSTOP`. 
 
 For example, to set the kill signal to SIGTERM, you would add:
 
 ```toml
 kill_signal = "SIGTERM"
@@ -62,16 +62,25 @@
 
 ### `kill_timeout` option
 
-<section class="warning">Note: `kill_timeout` settings should be considered best-effort, and your app needs to be prepared to handle shorter stopping times</section>
-
-This sets how long Fly.io waits (in seconds) after sending the `kill_signal` before moving on to a forced shutdown. Set `kill_timeout` to a value that gives your app enough time to exit gracefully. The default is 5 seconds. You can set it up to a maximum of 300 seconds (5 minutes).
+This sets how long Fly.io waits after sending the `kill_signal` before moving on to a forced shutdown. Set `kill_timeout` to a value that gives your app enough time to exit gracefully. The default is 5 seconds. You can set it up to a maximum of 300 seconds (5 minutes).
 
-For example, to set the timeout to two minutes:
+<section class="warning icon">**Accepted formats:** `kill_timeout` takes either an unquoted whole number of **seconds**, or a quoted duration string that includes a unit. A quoted number with no unit is a parse error, and a decimal number is silently truncated to `0`.</section>
 
 ```toml
-kill_timeout = 120
+kill_timeout = 120      # ✅ 120 seconds — unquoted, no unit
+kill_timeout = "2m"     # ✅ 2 minutes — quoted, with a unit
+kill_timeout = "120s"   # ✅ 120 seconds — quoted, with a unit
+
+kill_timeout = "120"    # ❌ error: missing unit in duration "120"
+kill_timeout = 1.5      # ❌ silently becomes 0 seconds — no grace period at all
 ```
 
+Valid units in the quoted form are the [Go duration units](https://pkg.go.dev/time#ParseDuration): `ns`, `us`, `ms`, `s`, `m`, and `h`. Only `s`, `m`, and `h` are meaningful here. Run `fly config validate` to confirm flyctl parses your value the way you expect.
+
+This top-level `kill_timeout` is the only place where an unquoted number means seconds. The separate `kill_timeout` key inside a [`machine_checks`](#services-machine_checks) section reads an unquoted number as **nanoseconds**, so it always needs the quoted, unit-bearing form.
+
+<section class="warning">Note: `kill_timeout` settings should be considered best-effort, and your app needs to be prepared to handle shorter stopping times</section>
+
 ### How the shutdown sequence works
 
 These options come into play during controlled shutdowns such as:
@@ -96,7 +105,7 @@
 
 ## Console command
 
 The command to run when you run the [`fly console` command](/docs/flyctl/console/). Configure the `console_command` field with the command that opens your framework's console, and then `fly console` will run that command automatically in a new, dedicated Machine. The new Machine is configured with the image and environment from your app’s latest release, but your app isn’t started, and no traffic will be routed to it. The Machine gets destroyed when you exit the console.
 
 Here's an example of a console command for Django:
 
@@ -116,7 +125,7 @@
 
 ## The `build` section
 
 The optional build section contains key/values concerned with how the application should be built. You can read more about builders in [Builders and Fly](/docs/reference/builders/)
 
 ### builder
 
@@ -125,7 +134,7 @@
   builder = "paketobuildpacks/builder-jammy-base"
 ```
 
 The builder "builder" uses CNB Buildpacks and Builders to create the application image. These are third party toolkits which can use Heroku compatible build processes or other tools. The tooling is all managed by the buildpacks and buildpacks are assembled into CNB Builders - images complete with the buildpacks and OS to run the tool chains.
 
 In our example above, the builder is being set to use [Paketo's all-purpose builder](https://paketo.io) which automatically detects needed buildpacks.
 
@@ -825,7 +834,7 @@
 * `entrypoint`: The entrypoint for the test. Defaults to the entrypoint of the Machine being tested if not set
 * `command`: The command to run for the test.
 * `kill_signal`: The signal to send to the test process if it runs too long. Defaults to the signal of the image, if a custom image is set.
-* `kill_timeout`: The time to wait before sending the kill signal. Defaults to the timeout of the image, if a custom image is set.
+* `kill_timeout`: The time to wait before sending the kill signal. Defaults to the timeout of the image, if a custom image is set. Unlike the [top-level `kill_timeout`](#kill_timeout-option), this one must be a **quoted duration string with a unit** — `kill_timeout = "5s"`. An unquoted `5` here is read as 5 *nanoseconds*, not 5 seconds.
 
 Machine checks are especially useful for `canary` deploys. `flyctl` will spawn a new Machine, ensure all machine capabilities are functional, and then deploy the rest of the Machines in your app.