CoreTrailKitGUIDEFirestore: read before writing in a transaction
Fix a Firestore Python ReadAfterWriteError by gathering transaction reads before queuing writes and keep retried callbacks free of external side effects.
#Google Cloud
3 min readProblems & solutions
65 articles
CoreTrailKitGUIDECoreTrailKitGUIDECloud Run functions: fix the Python entry point
Diagnose a missing Python function target, align the configured entry point with main.py, and verify the registered HTTP handler through Functions Framework.
#Google Cloud
3 min readCoreTrailKitGUIDEBigQuery: type an empty array of structs
Fix BigQuery Python’s empty STRUCT array parameter error with an explicit StructQueryParameterType, then verify the generated type and empty value representation.
#Google Cloud
3 min readCoreTrailKitGUIDEBigQuery Python: serialize Row results as JSON
Fix JSON serialization of a BigQuery Row by defining an explicit response shape and preserving timestamp and decimal semantics instead of stringifying every value.
#Google Cloud
3 min readCoreTrailKitGUIDEPub/Sub push: decode the message envelope
Fix a missing business field in a wrapped Pub/Sub push request by validating the envelope, decoding Base64 and UTF-8, and applying the expected JSON schema.
#Google Cloud
3 min readCoreTrailKitGUIDEPub/Sub Python: encode message data as bytes
Fix a Pub/Sub Python publisher TypeError by separating JSON serialization, UTF-8 byte encoding, client-library publishing, and direct REST Base64 representation.
#Google Cloud
3 min readCoreTrailKitGUIDECloud Storage: rewind a consumed upload stream
Diagnose “Stream must be at beginning” in a Python Cloud Storage upload, inspect a binary stream’s position, and reset it before sending the intended bytes.
#Google Cloud
3 min readCoreTrailKitGUIDECloud Storage 412: preserve generation checks
Investigate a Cloud Storage generation precondition failure, preserve an existing object, and distinguish create-only writes from deliberate version-based replacement.
#Google Cloud
3 min readCoreTrailKitGUIDEGoogle Cloud ADC: fix a stale credential path
Trace a DefaultCredentialsError to a stale GOOGLE_APPLICATION_CREDENTIALS path, distinguish CLI login from ADC, and repair the intended credential source.
#Google Cloud
3 min readCoreTrailKitGUIDEApp Service Health check: remove the redirect
Explain why a health URL works in a browser but fails App Service Health check, inspect the first HTTP response, and verify a direct meaningful health endpoint.
#Azure
3 min readCoreTrailKitGUIDEAzure Functions: register a Python Blueprint
Explain why a Python v2 function defined in a Blueprint is missing from the app, register it with FunctionApp, and verify metadata and the handler before deployment.
#Azure
3 min readCoreTrailKitGUIDEAzure Tables 409: handle an existing entity
Diagnose a duplicate Azure Table create from its PartitionKey and RowKey, preserve the existing entity, and choose create, update, or upsert semantics deliberately.
#Azure
3 min readCoreTrailKitGUIDEAzure Queue: use the current pop receipt
Explain why a Queue message delete fails with an old pop receipt after an update, retain the returned receipt, and verify deletion without confusing it with message identity.
#Azure
3 min readCoreTrailKitGUIDEAzure Queue: align message encoding policies
Diagnose a producer sending plain JSON to a Base64 consumer, make the Queue SDK policies explicit, and distinguish payload repair from a secondary SDK exception.
#Azure
3 min readCoreTrailKitGUIDEAzure Blob 412: handle an ETag conflict
Explain an Azure Blob conditional-write failure, keep the ETag associated with the content read, and reevaluate competing changes instead of forcing an overwrite.
#Azure
3 min readCoreTrailKitGUIDEAzure Blob SAS: check start and expiry times
Diagnose a SAS that is not yet valid or has expired, use timezone-aware UTC values, and regenerate an appropriate access window without editing the signed query.
#Azure
3 min readCoreTrailKitGUIDEAzure Blob SAS: fix missing write permission
Distinguish an Azure Blob SAS permission failure from bad credentials, compare the granted operation with an overwrite request, and verify a narrowly scoped repair.
#Azure
3 min readCoreTrailKitGUIDEAzure Identity: trace an unavailable credential
Diagnose an incomplete EnvironmentCredential, identify the authentication flow the app intends to use, and separate credential selection from Azure resource authorization.
#Azure
3 min readCoreTrailKitGUIDELambda: convert DynamoDB sets to JSON arrays
Diagnose a Lambda response marshal error caused by a DynamoDB string set, map the returned item to a deliberate JSON contract, and verify it in the official local runtime.
#AWS
3 min readCoreTrailKitGUIDEBoto3 throttling: set a clear retry budget
Diagnose a Boto3 call that gives up before a transient throttle clears, distinguish retries from total attempts, and verify the configured limit with a local HTTP fixture.
#AWS
3 min readCoreTrailKitGUIDEDynamoDB: handle a stale version conflict
Explain a ConditionalCheckFailedException during a versioned DynamoDB update, preserve the competing write, and reevaluate the operation instead of removing its condition.
#AWS
3 min readCoreTrailKitGUIDEDynamoDB GetItem: fix an incomplete primary key
Diagnose a DynamoDB GetItem ValidationException by comparing the full key schema and attribute types, then distinguish an invalid request from an item that is absent.
#AWS
3 min readCoreTrailKitGUIDELambda SQS: retry only failed batch records
Handle one failed SQS record without reporting a whole Lambda batch as failed, configure partial responses deliberately, and retain idempotency for redeliveries.
#AWS
3 min readCoreTrailKitGUIDELambda Python: fix a handler import error
Inspect a Python Lambda handler’s module name and deployment root, reproduce a misplaced app.py in the official local runtime, and verify the corrected layout.
#AWS
3 min readCoreTrailKitGUIDES3 wrong Region: inspect the signing scope
Compare an S3 bucket’s verified Region with the client and presigned credential scope, and repair URL generation without guessing from the visible hostname.
#AWS
3 min readCoreTrailKitGUIDES3 presigned upload: fix a signature mismatch
Compare a presigned S3 upload’s HTTP method and signed Content-Type with the actual request, preserve the URL exactly, and separate signature errors from access policy.
#AWS
3 min readCoreTrailKitGUIDEAWS profile: why the credentials are wrong
Diagnose a Boto3 session using unexpected environment credentials, compare implicit and explicit profiles, and verify the intended AWS identity before changing access.
#AWS
3 min readCoreTrailKitGUIDEPVC Pending: find a matching persistent volume
Investigate a Pending persistent volume claim by comparing capacity, storage class and selectors, then verify an appropriate binding without deleting existing data.
#Kubernetes
3 min readCoreTrailKitGUIDECreateContainerConfigError: check the Secret key
Diagnose a missing Secret key before the container starts, inspect names without exposing credentials, and verify that the corrected reference allows startup.
#Kubernetes
3 min readCoreTrailKitGUIDEConfigMap updated, but the Pod uses old values
Explain why editing a ConfigMap does not refresh an existing container’s environment, verify the old and new values, and roll out the intended application revision.
#Kubernetes
3 min readCoreTrailKitGUIDEPod Pending: inspect the CPU request
Diagnose an unscheduled Kubernetes Pod from its scheduler condition, distinguish CPU requests from current usage, and verify a workload that fits available capacity.
#Kubernetes
3 min readCoreTrailKitGUIDEKubernetes readiness: fix a failing HTTP probe
Explain why a running Pod receives no Service traffic when its readiness probe gets HTTP 404, verify the intended endpoint, and restore readiness without removing checks.
#Kubernetes
3 min readCoreTrailKitGUIDEKubernetes Service: correct a wrong targetPort
Trace a Service port to the application listener, distinguish ready backends from a working port mapping, and verify a corrected targetPort with an in-cluster request.
#Kubernetes
3 min readCoreTrailKitGUIDEKubernetes Service: fix an empty selector result
Diagnose a Service with no matching backends, compare its selector with Pod labels and EndpointSlices, and verify traffic after a narrowly scoped selector repair.
#Kubernetes
3 min readCoreTrailKitGUIDECrashLoopBackOff: inspect the previous container
Use previous-container logs and termination status to diagnose an application configuration failure, then verify the corrected workload rather than restarting blindly.
#Kubernetes
3 min readCoreTrailKitGUIDEKubernetes OOMKilled: verify the memory limit
Investigate an OOMKilled container, distinguish its memory limit from scheduling requests, and verify a measured change without treating exit 137 as a diagnosis.
#Kubernetes
3 min readCoreTrailKitGUIDESSH command not found: inspect the remote PATH
Explain why a tool works in an interactive terminal but fails through SSH, inspect the remote shell environment, and verify an explicit command and exit status.
#SSH
3 min readCoreTrailKitGUIDEscp no such file: check the remote directory
Diagnose a failed scp upload by checking the remote path and SFTP context, create only the intended destination, and verify the transferred file’s checksum.
#SSH
3 min readCoreTrailKitGUIDESSH broken pipe: test idle keepalives and limits
Investigate idle SSH disconnects, scope ServerAlive settings to the affected host, and distinguish detecting a dead connection from restoring a remote session.
#SSH
3 min readCoreTrailKitGUIDESSH timeout: find the failing connection stage
Distinguish an unreachable SSH port, an immediate refusal, and a server that never sends its SSH banner before changing keys or widening network access.
#SSH
3 min readCoreTrailKitGUIDESSH tunnel refused: check the remote destination
Trace a local SSH forward from its listener to the remote service, explain why tunnel setup can succeed before a request fails, and verify the correct endpoint.
#SSH
3 min readCoreTrailKitGUIDESSH ProxyJump: reach a private server safely
Diagnose a private SSH target behind a bastion, configure separate identities for each hop, and verify access without copying keys or forwarding your agent.
#SSH
3 min readCoreTrailKitGUIDESSH config: fix an alias using the wrong account
Use ssh -G to inspect an alias, find a general Host rule that wins too early, and test a corrected configuration before editing your normal SSH setup.
#SSH
3 min readCoreTrailKitGUIDESSH publickey denied: inspect file permissions
Separate local private-key rejection from server authorized_keys permissions, reproduce both failures, and verify the intended account without weakening SSH checks.
#SSH
4 min readCoreTrailKitGUIDESSH host key changed: verify before replacing
Investigate an SSH host key warning, compare fingerprints through a trusted channel, and replace only the verified host entry without disabling identity checks.
#SSH
3 min readCoreTrailKitGUIDEPostgres in Docker: rotate an existing password
Explain why changing POSTGRES_PASSWORD does not reset an initialized database, verify authentication from another container, and rotate the role without deleting its volume.
#Docker
4 min readCoreTrailKitGUIDEDocker COPY fails: check the build context
Diagnose Docker COPY source-not-found and checksum errors by checking the context root, .dockerignore, and filename before disabling cache or widening the build.
#Docker
3 min readCoreTrailKitGUIDEDocker Compose: trace environment overrides
Explain why a Compose service sees the wrong environment value by separating model interpolation, env_file, environment, shell exports, and run overrides.
#Docker
3 min readCoreTrailKitGUIDEDocker entrypoint: fix CRLF script failures
Diagnose an entrypoint that exists but fails with no such file, inspect shebang bytes and interpreter availability, then rebuild an LF-normalized script.
#Docker
4 min readCoreTrailKitGUIDEDocker exit 137: confirm OOM before tuning RAM
Distinguish a container memory-limit kill from another SIGKILL, inspect OOMKilled and limits, and verify a bounded workload before changing memory settings.
#Docker
4 min readCoreTrailKitGUIDEDocker volumes: fix non-root permission denied
Trace a Docker volume write failure to numeric ownership, reproduce it with a non-root UID, and fix the specific file without granting world-write access.
#Docker
4 min readCoreTrailKitGUIDEDocker bind mounts: find hidden image files
Explain why files exist in a Docker image but disappear in Compose, compare mounts with an unmounted container, and narrow the mount without rebuilding blindly.
#Docker
4 min readCoreTrailKitGUIDEDocker: fix a port that is already allocated
Find the owner of a conflicting host port, distinguish published and container ports, and verify a new loopback mapping without stopping unrelated services.
#Docker
4 min readCoreTrailKitGUIDEDocker Compose: wait for a healthy dependency
Diagnose first-start connection failures in Docker Compose, add a meaningful healthcheck, and verify service_healthy without treating startup order as runtime recovery.
#Docker
4 min readCoreTrailKitGUIDEASP.NET Core container connection reset after an image upgrade: verify port 8080
Diagnose a .NET container that runs but stops serving through an old port-80 mapping. Compare image defaults, Kestrel binding, and effective environment settings.
#.NET
4 min readCoreTrailKitGUIDEPython externally-managed-environment: use a venv
Understand why pip refuses a system-managed Python install, select the intended interpreter, and verify dependencies inside an isolated project environment.
#Python
4 min readCoreTrailKitGUIDENode.js ERR_MODULE_NOT_FOUND after a build: check the emitted import path
Diagnose relative ESM imports that work in tooling but fail in Node. Check file extensions, package mode, build output, and exact filename casing.
#Node.js
4 min readCoreTrailKitGUIDEnpm ci fails with an out-of-sync lockfile: repair the dependency contract
Fix npm ci failures caused by package.json and package-lock.json disagreement without replacing a reproducible CI install with an uncontrolled npm install.
#npm
4 min readCoreTrailKitGUIDEJava UnsupportedClassVersionError: compare the build JDK with the runtime
Diagnose class-file version mismatches, choose between upgrading the runtime and targeting an older release, and verify the packaged artifact.
#Java
4 min readCoreTrailKitGUIDECloud Run “failed to start and listen on PORT”: check the listener before the timeout
Fix a Cloud Run service that never becomes ready by checking its bind address, injected PORT, entrypoint, and earliest revision logs.
#Google Cloud
4 min readCoreTrailKitGUIDEAzure App Service container startup fails: match the app port to the routing model
Diagnose Linux custom-container startup failures by checking the application listener, App Service container mode, routing port, and container logs.
#Azure
4 min readCoreTrailKitGUIDEAWS Lambda times out after joining a VPC: trace the outbound route
Investigate public HTTPS requests that stop working after a Lambda VPC change. Check routes, NAT, DNS, and network policy before increasing timeouts.
#AWS
4 min readCoreTrailKitGUIDEKubernetes restart loops: fix startup probes
Separate probe-triggered restarts from application crashes and OOM kills. Give initialization a measured startup budget without hiding real failures.
#Kubernetes
4 min readCoreTrailKitGUIDESSH “Too many authentication failures”: select the key before retrying
Find out why SSH can disconnect before offering the correct key. Inspect effective configuration and limit the identities used for one host.
#SSH
4 min readCoreTrailKitGUIDEDocker Compose: fix localhost connection refused
Diagnose connections that work from your host but fail inside a Compose service. Separate service names, container ports, bind addresses, and startup readiness.
#Docker
4 min read