Troubleshooting Knowledge Transformer

1. Check the pod logs for error messages:

   oc logs -n wxa4z-zad -l app=wxa4z-transform --tail=100

2. Consider common errors and solutions:

   "Secret not found: transform-secret"

   Error

   The transform secret was not created before deployment.

   Solution

   Create the secret and restart the pod:

   oc apply -f transform-secret.yaml
        oc delete pod -n wxa4z-zad -l app=wxa4z-transform

   "Missing required environment variable: MODEL_RUNTIME"

   Error

   The watsonx credentials secret is missing or incomplete.

   Solution

   Verify the wxa4z-ifm-credentials secret contains all the required keys:

   oc get secret wxa4z-ifm-credentials -n wxa4z-zad -o jsonpath='{.data}' | jq 'keys'

   The required keys are: MODEL_RUNTIME, LLM_BASE_URL, LLM_API_KEY, WATSONX_MODEL_ID, and WATSONX_PROJECT_ID.

   "Failed to connect to LLM endpoint"

   Error

   The LLM endpoint is unreachable or credentials are invalid.

   Solution

   1. Verify LLM credentials and connectivity. Check LLM_BASE_URL:

      oc get secret wxa4z-ifm-credentials -n wxa4z-zad -o jsonpath='{.data.LLM_BASE_URL}' | base64 -d

   2. Test connectivity from within the cluster:

      oc run -it --rm debug --image=curlimages/curl --restart=Never -- curl -k <LLM_BASE_URL>/health

3. If the issue persists, check resource constraints:

   oc describe pod -n wxa4z-zad -l app=wxa4z-transform

   Look for events indicating insufficient resources (CPU, memory, or ephemeral storage).

1. Check the current route timeout:

   oc get route wxa4z-transform -n wxa4z-zad -o jsonpath='{.metadata.annotations.haproxy\.router\.openshift\.io/timeout}'

2. For large files or complex transformations, increase the timeout in your deploy-zad.yaml:

   transform:
     route:
       annotations:
         haproxy.router.openshift.io/timeout: 60m

3. Apply the changes:

   oc apply -f deploy-zad.yaml

1. Verify the API key is correct:
   1. Get the API key from the secret:

      CORRECT_API_KEY=$(oc get secret transform-secret -n wxa4z-zad -o jsonpath='{.data.TRANSFORM_API_KEY}' | base64 -d)

   2. Compare with your configured key:

      echo "Secret API key: $CORRECT_API_KEY"
         echo "Your API key: $TRANSFORM_API_KEY"

2. Reconfigure the zassist CLI with the correct API key:

   zassist config transform set-api-key $CORRECT_API_KEY

3. Verify the configuration:

   zassist config transform show

1. Verify that the API is running:

   curl [your-api-url]/health

2. Check your API URL configuration:

   zassist transform config show

3. Update the API URL if needed:

   zassist transform config [new-api-url]

1. Check the current configuration:

   zassist transform config show

2. Re-configure the API URL:

   zassist transform config http://localhost:8080

3. Verify the configuration file exists at ~/.zassist/config.json.
4. Manually override the API URL for the current session:

   export TRANSFORM_API_URL="http://localhost:8000"

1. Check the transform pod logs for specific LLM errors:

   oc logs -n wxa4z-zad -l app=wxa4z-transform --tail=50 | grep -i error

2. Common LLM errors:

   "Model not found"

   Error

   The WATSONX_MODEL_ID is incorrect or the model is not deployed.

   Solution

   Verify the model ID in the watsonx credentials.

   oc get secret wxa4z-ifm-credentials -n wxa4z-zad -o jsonpath='{.data.WATSONX_MODEL_ID}' | base64 -d

   "Quota exceeded" or "Rate limit"

   Error

   The LLM service has rate limits or quota restrictions.

   Solution

   Wait and retry the connection, or contact your LLM service administrator.

   "SSL certificate verification failed"

   Error

   TLS verification is enabled but the certificate is not trusted.

   Solution

   • Either disable TLS verification (not recommended for production environments):

     transform:
       env:
         LLM_TLS_VERIFY: "false"

   • Or configure custom CA certificates:

     transform:
       env:
         LLM_TLS_VERIFY: "true"
         SSL_CERT_FILE: "/etc/ssl/llm/llm-cert.pem"
         REQUESTS_CA_BUNDLE: "/etc/ssl/llm/llm-cert.pem"

1. Use transform, not upload.
2. When running from the cli/ directory, include the ./ prefix:

   ./zassist transform document.pdf ./knowledge

3. If installed to your system PATH, run without the ./ prefix:

   zassist transform document.pdf ./knowledge

1. Check that the file path is correct.
2. Use absolute paths or ensure that you are in the correct directory.
3. Verify file permissions.

1. Increase the timeout value using the --timeout flag (default is 30 minutes):

   zassist transform large-file.vtt ./knowledge --timeout 60m

2. For very large files, use a longer timeout:

   zassist transform huge-file.vtt ./knowledge -t 2h

1. Check current resource usage:

   oc top pod -n wxa4z-zad -l app=wxa4z-transform

2. Increase resource limits in your deploy-zad.yaml file:

   transform:
     resources:
       requests:
         cpu: 1
         memory: 1Gi
       limits:
         cpu: 4
         memory: 2Gi
         ephemeral-storage: "16Gi"  # Increase for large files

3. Apply the changes:

   oc apply -f deploy-zad.yaml

1. Check disk space.
2. Verify write permissions in the current directory.
3. Ensure input files are accessible.

1. Check API logs for details.
2. Verify the context blob structure (should have input/ and knowledge/ directories).
3. Check API documentation at [your-api-url]/docs

1. Check if the API requires authentication (look for SECURE MODE ENABLED in API logs).
2. Set the API key:

   export TRANSFORM_API_KEY=[your-api-key-here]

3. Verify the API key is correct.
4. Ensure the API key environment variable is set in your current session.
5. Check if the API key matches the one configured on the API server.

export TRANSFORM_API_KEY=[your-api-key-here]

1. Check the list of supported file formats displayed in the error message.
2. Remove unsupported files from your input directory.
3. Convert unsupported files to a supported format. For more information about supported formats, see Supported file formats.