docs: troubleshooting and additional packages version pinning (#3092)

- Connection error troubleshooting
- Additional packages version pinning
- Realtime stream error troubleshooting

Author: isshaddad

docs/config/extensions/additionalPackages.mdx

@@ -14,21 +14,25 @@ export default defineConfig({
   project: "<project ref>",
   // Your other config settings...
   build: {
+    // Omit version for auto-resolution; for reproducible builds use e.g. packages: ["wrangler@X.Y.Z"]
     extensions: [additionalPackages({ packages: ["wrangler"] })],
   },
 });
 ```
 
-This allows you to include additional packages in the build that are not automatically included via imports. This is useful if you want to install a package that includes a CLI tool that you want to invoke in your tasks via `exec`. We will try to automatically resolve the version of the package but you can specify the version by using the `@` symbol:
+This allows you to include additional packages in the build that are not automatically included via imports. This is useful if you want to install a package that includes a CLI tool you can invoke in your tasks via `exec`. We will try to automatically resolve the version of the package but you can specify the version by using the `@` symbol.
+
+If you omit the version, the build may use a cached or older resolution. For reproducible builds, pin the exact version (e.g. `wrangler@X.Y.Z`).
 
 ```ts
 import { defineConfig } from "@trigger.dev/sdk";
+import { additionalPackages } from "@trigger.dev/build/extensions/core";
 
 export default defineConfig({
   project: "<project ref>",
   // Your other config settings...
   build: {
-    extensions: [additionalPackages({ packages: ["wrangler@1.19.0"] })],
+    extensions: [additionalPackages({ packages: ["wrangler@X.Y.Z"] })],
   },
 });
 ```

docs/troubleshooting.mdx

@@ -45,6 +45,14 @@ The Yarn Plug'n'Play manifest forbids importing "@trigger.dev/core" here because
 
 And you're using Yarn v1.22 or another package manager, check if you have a `.pnp.cjs` file in your home directory. This can happen if you previously had Yarn Plug'n'Play enabled globally. Remove the `.pnp.cjs` file to resolve the issue.
 
+### `Connection error` when logging in
+
+If you see "Connection error" when running `trigger login` (or "Failed to create authorization code"), try these in order:
+
+1. **Clear saved auth and retry:** `npx trigger.dev@latest logout`, then `npx trigger.dev@latest login` again. Sometimes an invalid config is cached.
+2. **VPN or firewall:** Disconnect from VPN or check firewall/proxy; try `npx trigger.dev@latest login --log-level debug` for more detail.
+3. **TLS / certificate store:** Node may use a different CA store than your OS (e.g. `curl` works but the CLI fails). Try `export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem` (macOS/Linux) then login again, or reinstall Node so it gets updated certs. Behind a corporate proxy or custom CA? Set `NODE_EXTRA_CA_CERTS` to that CA file.
+
 ## Deployment
 
 Running the [trigger.dev deploy] command builds and deploys your code. Sometimes there can be issues building your code.
@@ -270,6 +278,23 @@ You could also offload the CPU-heavy work to a Node.js worker thread, but this i
 
 If the above doesn't work, then we recommend you try increasing the machine size of your task. See our [machines guide](/machines) for more information.
 
+### Realtime stream error (`sendBatchNonBlocking` / `S2AppendSession`)
+
+Errors mentioning `sendBatchNonBlocking`, `@s2-dev/streamstore`, or `S2AppendSession` (often with `code: undefined`) can occur when you close a stream and then await `waitUntilComplete()`, or when a stream runs for a long time (e.g. 20+ minutes). Wrap `waitUntilComplete()` in try/catch so Transport/closed-stream errors don't fail your task:
+
+```ts
+import { streams } from "@trigger.dev/sdk";
+
+const { waitUntilComplete } = streams.pipe("my-stream", dataStream); // or streams.writer(...)
+try {
+  await waitUntilComplete();
+} catch (err) {
+  // Transport/closed-stream; log if needed or ignore
+}
+```
+
+Alternatively, await `waitUntilComplete()` before closing the stream. See [Realtime Streams](/tasks/streams) for more.
+
 ## Framework specific issues
 
 ### NestJS swallows all errors/exceptions