Troubleshooting

Common issues

Error: agent 'demo-1' not found

• Verify the agent name with clish agent show
• Check if the agent was created successfully

• Generate a new token with clish agent onboarding-token issue
• Ensure agent uses the correct token for connection

Credential validation issues

Error: Agent did not respond to credential validation within timeout period

• Agent cannot reach the SVM (network issues, firewall blocking)
• Agent is overwhelmed or unresponsive
• SVM is down or unreachable

1. Review agent logs for SVM connection errors
2. Test network connectivity from the agent to SVM:
   • Verify SVM management LIF is reachable from agent pod
   • Check firewall rules between agent and SVM
3. Re-onboard the agent and issue a new onboarding token via Management Service CLI:
   clish agent re-onboard --instance <agent-name>
4. Modify the config.yaml file in the ONTAP agent installation folder (default: C:\Program Files\v1fs-ontap-agent\)
5. Remove the device_token key and its value
6. Add the onboarding_token key with the newly issued token:
   onboarding_token: eyJh......
7. Start the ONTAP agent service (v1fs-ontap-agent)
8. Verify the agent connection status using Management Service CLI
9. After the agent connects successfully, re-enter credentials using:

   clish agent credential modify --instance <agent-name>

Note When validation fails or times out, credentials are automatically rolled back to the previous working version to prevent service disruption.

Credentials rejected by SVM

Error: Agent rejected credentials: Failed to connect to SVM: authentication failed

• Invalid username or password
• SVM user account is locked, expired, or disabled
• User lacks required permissions on SVM
• ONTAP API is not accessible

1. Verify credentials are correct:
   • Check username spelling and case sensitivity
   • Ensure password matches SVM user account
   • Verify you're using the correct SVM management credentials
2. Check SVM user account status (on ONTAP CLI):
   security login show -user-or-group-name <username> -vserver <svm-name>
   Look for:
   • Account locked status
   • Password expiration
   • Authentication method (should be "password" or "domain")
3. Verify user has appropriate permissions:
   • User should have at least readonly or vsadmin role for the SVM
   • Check role assignments:

     security login show -vserver <svm-name>
     security login role show -vserver <svm-name> -role <role-name>

4. Check SVM API access:
   # On ONTAP CLI vserver services web show -vserver <svm-name>
   Ensure ONTAPI and REST API are enabled
5. Review ONTAP audit logs for failed authentication attempts:

   # On ONTAP CLI 
   event log show -severity error -message-name *authentication*

Agent state invalid for credential update

Error: agent 'demo-1' is in state 'onboarding', cannot set credentials

• Agent must be in credential-required or running state to accept credential updates
• Agent may be stuck in a transitional state

1. Check the current agent state:
   clish agent show --instance <agent-name>
   Note the State and Connected fields
2. If the agent is stuck in onboarding state:
   • Verify the agent has completed initial onboarding process
   • Check if the agent successfully connected with onboarding token
3. If the agent is in init state:
   • The agent needs to complete initial connection first
   • Ensure the onboarding token is correctly configured in agent config
   • Restart the agent with valid onboarding token
4. If the agent is in disconnected state:
   • Verify network connectivity between agent pod and management service
   • Check the management service logs for connection errors

Agent not connected via WebSocket

Error: agent 'demo-1' is not connected via WebSocket, cannot validate credentials

• Credential validation requires an active WebSocket connection to send credentials and receive validation result
• The agent service may be down, restarting, or having network issues

1. Verify that the agent service is running.
2. Check the agent connection status:
   clish agent show --instance <agent-name>
   Look for Connected: disconnected
3. Review the agent logs for WebSocket connection errors
4. Check the network connectivity:
   • Verify that the agent can reach management service WebSocket endpoint
   • Check for network policies or firewalls blocking WebSocket connections
5. Wait for the agent to reconnect:
   • Agents automatically attempt to reconnect on disconnection
   • Monitor connection status
6. If the agent does not reconnect, check if the device token has expired (may need clish agent re-onboard)

Useful commands for debugging

clish agent show

clish agent show --instance <agent-name>

clish scanner scan-policy show