Troubleshooting

Common issues and solutions when using the AVEVA Integration Service Data API SDK.

Connection Issues

Problem: Cannot Connect to DataAPI

Symptoms: HubConnectionInitializationException, connection timeout, Unable to connect to remote server.

Solutions:

Verify Host URL format

// Correct

var host = "https://your-ais-server/api/v1/datasources";

// NOT: http://... (must be HTTPS)

// NOT: https://your-ais-server/api (missing /v1/datasources)

Test Network Connectivity

# Windows PowerShell

Test-NetConnection -ComputerName your-ais-server -Port 443

ping your-ais-server

Check Firewall Rules

• Ensure port 443 (HTTPS) is open outbound

• Check proxy settings if applicable

Test Connection Manually

using var client = new HttpClient(

new HttpClientHandler { UseDefaultCredentials = true });

try

{

var response = await client.GetAsync("https://your-ais-server/api/v1/datasources");

Console.WriteLine($"Status: {response.StatusCode}");

}

catch (Exception ex)

{

Console.WriteLine($"Connection failed: {ex.Message}");

}

Problem: Request Timeout

Symptoms: TimeoutException, "The operation has timed out", very slow then failure

Solutions:

1. Increase Timeout

   var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

   host: host,

   authType: AuthenticationType.NTLM,

   waitingTimeInMinutesForLiveData: 300 // Increase from default 60

   );

2. Check Server Load - Contact the server administrator; monitor network latency

3. Try from a Different Location - Helps isolate network vs. server issues

Authentication Issues

Problem: 401 Unauthorized

For NTLM:

4. Verify Domain Membership

   whoami # Check current user

   whoami /all # Check domain and group membership

5. Verify Domain Controller Access

   Test-NetConnection -ComputerName <domain-controller> -Port 389

6. Try Connect Authentication (if NTLM fails)

   var token = await GetAccessToken();

   var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

   host: host,

   authType: AuthenticationType.Connect,

   token: token);

For Connect / Token:

7. Verify Token is Not Expired

   // Decode and check expiry (requires System.IdentityModel.Tokens.Jwt)

   var tokenHandler = new JwtSecurityTokenHandler();

   var jwt = tokenHandler.ReadJwtToken(token);

   if (jwt.ValidTo < DateTime.UtcNow)

   Console.WriteLine("Token has expired");

8. Request a Fresh Token

   var newToken = await tokenManager.GetValidToken(forceRefresh: true);

9. Verify Token Scope – Ensure the token includes the api scope; contact Connect admin

Problem: 403 Forbidden

Symptoms: Authenticated but access denied

Solutions:

• Verify the user has DataAPI access rights and appropriate role assignment

• Check if the user can access specific data sources

• Contact the server administrator or data owner

Data Retrieval Issues

Problem: No Data Returned / EmptyDataObjectRecievedException

10. Verify the datasource exists

    var datasources = await client.GetDataSources("");

    var exists = datasources.Any(x => x.Name == "MyDataSource");

    Console.WriteLine($"Exists: {exists}");

11. Verify the table exists

    var tables = await client.GetTables("MyDataSource", "");

    var tableExists = tables.Any(x => x.Name == "MyTable");

    Console.WriteLine($"Table exists: {tableExists}");

12. Try without filter first

    // If this returns data, your filter was too restrictive

    var allData = await client.GetTableData("DataSource", "Table", "");

13. Check datasource type matches client

    var ds = await client.GetDataSource("MyDataSource", "");

    Console.WriteLine($"Type: {ds.Type}");

    // Must match the client type (Engineering, Excel, etc.)

Problem: Incorrect Data Returned

14. Verify exact datasource name (case-sensitive)

    var sources = await client.GetDataSources("");

    foreach (var s in sources)

    Console.WriteLine($"'{s.Name}' ({s.Type})");

15. Review filter syntax

    // OData-style; check the API documentation for exact syntax

    var data = await client.GetTableData("DS", "Table",

    "Status eq 'Active' and Modified gt datetime'2024-01-01'");

Pub/Sub Issues

Problem: Cannot Subscribe to Topic

Symptoms: HubConnectionInitializationException, subscribe hangs or fails

16. Verify the SignalR hub is accessible – Test hub URL (usually /api/hub).

17. Check topic existence – The topic must exist before subscribing.

18. Inspect connection setup.

    var pubSubClient = await SignalRHubConnectionFactory.CreatePubSubClient(

    httpClientFactory, hubConnectionManager, authType, host);

Problem: Messages Not Received

Symptoms: Subscribe succeeds but no messages arrive; DataPostMessageNotReceivedException

19. Verify message is published correctly

    var result = await pubSubClient.Publish(message, host, topic);

    if (string.IsNullOrEmpty(result))

    Console.WriteLine("Publish returned empty result");

20. Check Broadcast message format

    var message = new Broadcast

    {

    PublisherConnectionId = connectionId ?? "",

    CreatedTime = DateTime.UtcNow,

    User = Environment.UserName,

    AcknowledgementId = Guid.NewGuid().ToString(),

    CallbackURL = "",

    Context = "Message content"

    };

21. Implement reconnection logic – Hub connections can drop due to network issues.

Performance Issues

Problem: Slow Response Times

22. Filter server-side to reduce data

    // Preferred – filter before transfer

    var filtered = await client.GetTableData("DS", "Table", "Status eq 'Active'");

23. Reuse client instances – Do not create a new client per request.

24. Monitor network latency – High latency between client and server can result in response delays.

Problem: Memory Leaks

25. Dispose resources

    using var httpClient = new HttpClient(); // Disposed automatically

26. Limit concurrency

    private readonly SemaphoreSlim _semaphore = new(3);

    public async Task<T> LimitedRequest<T>(Func<Task<T>> operation)

    {

    await _semaphore.WaitAsync();

    try { return await operation(); }

    finally { _semaphore.Release(); }

    }

27. Stream large result sets – Iterate IEnumerable<T> rather than materialising all at once

Configuration Issues

Problem: Configuration Not Loaded

28. Verify file exists in output directory – Check the file is copied on build.

29. Check configuration key name exactly.

    var host = ConfigurationManager.AppSettings["host"]; // lowercase "host"

    // NOT: AppSettings["Host"] – case-sensitive!

30. Debug available keys

    foreach (var key in ConfigurationManager.AppSettings.AllKeys)

    Console.WriteLine($" {key} = {ConfigurationManager.AppSettings[key]}");

Getting More Help

Collect Diagnostic Information

When reporting issues, include:

31. Full Error and Stack Trace

    catch (Exception ex)

    {

    Console.WriteLine($"Error: {ex.Message}");

    Console.WriteLine($"Stack Trace: {ex.StackTrace}");

    if (ex.InnerException != null)

    Console.WriteLine($"Inner: {ex.InnerException.Message}");

    }

32. SDK Version

    var version = typeof(DataApiClientFactory).Assembly.GetName().Version;

    Console.WriteLine($"SDK Version: {version}");

33. .NET Version

    dotnet --version

34. Environment: OS, domain/corporate network membership, proxy configuration.

Frequently Asked Questions

Q: Can I use the SDK from the cloud?

A: Yes, if using Connect authentication. NTLM requires access to the corporate domain.

Q: How do I increase the timeout?

A: Use waitingTimeInMinutesForLiveData:

var client = DataApiClientFactory.CreateDataApiClient<EngineeringClient>(

host, authType, waitingTimeInMinutesForLiveData: 300);

Q: Can I cache API responses?

A: Yes, but consider data freshness. Implement a cache invalidation strategy.

Q: How do I handle Pub/Sub disconnections?

A: Implement reconnection logic with exponential backoff. Treat HubConnectionInitializationException as a transient error.

Q: Is the SDK thread-safe?

A: HttpClient and typed clients are thread-safe. HubConnection operations are thread-safe; token management is your responsibility.