Troubleshoot the Services API configuration

You can use the information in the following sections to troubleshoot the configuration of the Services API. In addition to reviewing error messages, you can also use the Proxy Diagnostic Tool to troubleshoot connections to the Services API. See Test the Services API configuration.

This page contains the following information about logging options:

• Common causes of Services API errors
• Log and debug settings in the web.config file
• Production environment trace settings
• Test environment trace settings
• FailureAuditing Configuration Override Setting

This page contains the following information about error messages:

• Attempts to access an .svc file cause a keyset error
• Catch EndpointType exceptions
• Connection errors in load-balanced systems
• Could not load type 'System.ServiceModel.Activation.HttpModule'
• Erroneous calls to internal web server in load-balanced systems
• HTTP error 404.17 or 404.3
• Incorrect version of .NET enabled for application pools
• Missing handler mappings
• Pipe endpoint could not be found
• System.ServiceModel.ExceptionDetail Error
• Unable to access .svc file path in browser
• Unable to access website
• Error occurs when machines in a workgroup attempt to log in
• Update the HTTP host header

Common causes of Services API errors

In the Services API, the following conditions result in an error:

• Required fields aren't included in a method call
• Permission levels are inadequate for the specified operation
• Values passed to methods aren't within a predefined range or object type

For many operations, a message indicating an error is returned in the ResultSet collection. Each object in the collection has a Success/Status field of type Boolean and Message description field. When an error occurs, the Success/Status field is set to False, and an error description is added to the Message field. The Services API throws an exception when a communication failure, timeout, or other serious error occurs, which is transmitted back to the client as a SOAP Fault that can be caught.

Log and debug settings in the web.config file

To assist with Services API troubleshooting, enable logging and debugging in the web.config file. (They are disabled by default.) Modify the configuration settings as necessary.

Production environment trace settings

To troubleshoot application activity, you can collect trace data from WCF or user-defined trace sources. Trace levels include Warning, Information, and Verbose.

Note: Logging may result in application performance degradation. Information and Verbose levels produce greater logging output resulting in a greater performance impact, so they may be best suited for non-production environments.

This table includes logging configurations recommended for production environments. You will need to update the web.config file with these values. (If you don't anticipate performance degradation, you can set the switchValue attribute to Information to generate additional trace data.)

Trace Source	Source Name	switchValue Attribute	Additional Attribute
WCF	System.ServiceModel	Warning	propagateActivity="true"
User-defined	User-defined source name	Warning, ActivityTracing

Using the recommended production environment configurations, the following sample code defines trace settings for the System.ServiceModel WCF trace source and a user-defined trace source named myUserTraceSource:

<system.diagnostics>
     <sources>
          <source name="System.ServiceModel"
                    switchValue="Warning"
                    propagateActivity="true" >
               <listeners>
                    <add name="xml"/>
               </listeners>
          </source>
          <source name="myUserTraceSource"
                    switchValue="Warning, ActivityTracing">
               <listeners>
                    <add name="xml"/>
               </listeners>
          </source>
     </sources>
     <shareListeners>
          <add name="xml"
               type="System.Diagnostics.XmlWriterTraceListener"
               initializeData="C:\logs\Traces.svclog" />
     </sharedListeners>
</system.diagnostics>
        

Test environment trace settings

In your test environment, make the following updates to the web.config file:

• In the initializeData attribute, set the file name and directory location to the folder where you want to save the log output.
• Add the following node to the system.servicemodel section:

  <diagnostics wmiProviderEnabled="true">
       <messageLogging
            logEntireMessage="true"
            logMalformedMessages="true"
            logMessagesAtServiceLevel="true"
            logMessagesAtTransportLevel="true"
            maxMessagesToLog="3000"
       />
  </diagnostics>

Use the recommended configuration settings for the test environment listed in the following table. For enhanced logging, add System.ServiceModel.MessageLogging as an additional trace source. (The switchValue attribute doesn’t affect this trace source.)

Trace Source	Source Name	Source Name	Additional Attribute
WCF	System.ServiceModel	Information, ActivityTracing or Verbose, ActivityTracing	propagateActivity="true"
User-defined	User-defined source name	Information, ActivityTracing or Verbose, ActivityTracing

The following sample code defines trace settings for the System.ServiceModel WCF, and the System.ServiceModel.MessageLogging trace sources, as well as a user-defined trace source named myUserTraceSource. The switchValue attribute uses this Information, and ActivityTracing settings.

<system.diagnostics>
     <sources>
          <source name="System.ServiceModel"
                    switchValue="Information, ActivityTracing"
                    propagateActivity="true" >
               <listeners>
                    <add name="xml"/>
               </listeners>
          </source>
          <source name="System.ServiceModel.MessageLogging">
               <listeners>
                    <add name="xml"/>
               </listeners>
          </source>
          <source name="myUserTraceSource"
                    switchValue="Information, ActivityTracing">
               <listeners>
                    <add name="xml"/>
               </listeners>
          </source>
     </sources>
     <sharedListeners>
          <add name="xml"
               type="System.Diagnostics.XmlWriterTraceListener"
               initializeData="C:\logs\Traces.svclog" />
     </sharedListeners>
</system.diagnostics>
        

FailureAuditing Configuration Override Setting

You can also configure a FailureAuditing override setting on the server hosting the Services API. You can set this value to True if you want to audit failed security events from WCF. Audited security events include transport, message, or negotiate authentication and authorization events. You can view these events in the Windows Event Viewer, since they are written to Windows event log. See Configure the Services API.

Attempts to access an .svc file cause a keyset error

You receive the following error message when accessing a .svc files that expose an EndpointType configuration requiring a certificate, such as username and password authentication for HTTP, HTTPS, or Net.TCP:

Keyset does not exist.

This error occurs because the permissions on the private key of the certificate are incorrect. It occurs only when the Services API attempts to access a certificate already added to a directory, even though it is in the correct location. You don’t need to relocate the certificate.

To resolve this issue, you need to ensure the account running the Relativity.Services application in IIS has access to the private key of the certificate. Complete these steps to set the permissions:

1. Log on to the server running the Services API.
2. Click Start.
3. In the Search programs and files box, type mmc.
4. Press Enter to open the Microsoft Management Console.
5. On the File menu, click Add/Remove Snap-in.
6. In the Available snap-ins column, double-click Certificates to open the Certificates snap-in dialog.
7. Select Computer account, and click Next.
8. Select Local computer option for managing snap-ins.
9. Open the Certificates (Local Computer) snap-in.
10. Browse to Personal, and then Certificates.
11. Locate the certificate that you have set for CertificateFindValue property in the web.config file.
12. Right-click on the certificate, point to All Tasks, and click Manage Private Keys.
13. To modify the private key permissions, select Add.
14. Grant full permissions to the account running the Relativity.Services IIS application.

Catch EndpointType exceptions

You can obtain additional information about EndpointType errors by catching the EndpointTypeCollectionInvalidException exception. This error message is returned when you catch this exception:

Error constructing a proxy.

Log Info:

EndpointType UserNamePasswordNetTCPHTTP Failed:

-->Metadata contains a reference that cannot be resolved: 'http://someserver.name.domain/Relativity.Services/SetExecutorNetHTTP.svc?wsdl'.

-->The remote name could not be resolved: 'someserver.name.domain'

EndpointType UserNamePasswordHTTP Failed:

-->Metadata contains a reference that cannot be resolved: 'http://someserver.name.domain/Relativity.Services/SetExecutorHTTP.svc?wsdl'.

-->The remote name could not be resolved: 'someserver.name.domain'

EndpointType UserNamePasswordNetTCPHTTPS Failed:

-->Metadata contains a reference that cannot be resolved: 'https://someserver.name.domain/Relativity.Services/SetExecutorNetHTTPS.svc?wsdl'.

-->The remote name could not be resolved: 'someserver.name.domain'

EndpointType UserNamePasswordHTTPS Failed:

-->Metadata contains a reference that cannot be resolved: 'https://someserver.name.domain/Relativity.Services/SetExecutor.svc?wsdl'.

-->The remote name could not be resolved: 'someserver.name.domain'

Connection errors in load-balanced systems

If you have configured your environment for load balancing and HTTPS, you may receive errors if the API connects to a different URL than the WSDL. To resolve these errors, set the binding in IIS to a certificate from an internal CA authority or to a wildcard certificate.

Could not load type 'System.ServiceModel.Activation.HttpModule'

This error is displayed if you have installed .NET 4.0 features after installing .NET 4.6.2:

Server Error in '/Relativity.Services' Application.

Could not load type 'System.ServiceModel.Activation.HttpModule' from assembly 'System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089'.

Open a Visual Studio 64-bit console. In Admin mode, execute this command:

     aspnet_regiis.exe /iru
        

The program, aspnet_regiis.exe, is located in one of the following directories by default. The minor version number in the directory path may vary, such as .30319 in this example.

     %windir%\Microsoft.NET\Framework64\v4.0.30319
     %windir%\Microsoft.NET\Framework\v4.0.30319
        

If the previous command didn't resolve the issue, execute this command:

servicemodelreg -r
        

For more information, see The DCS ServiceModelReg Utility on the Microsoft Developer Network site.

Erroneous calls to internal web server in load-balanced systems

When you use the client proxy to access the Services API, a second erroneous call is made to an internal web server. The URIs in the WSDL document points to inaccessible internal websites. Microsoft has identified this behavior as a known issue exhibited by the WCF service in load-balanced environments. The following environmental configurations are associated with this issue:

• Windows Communication Foundation (WCF) service in a load-balanced environment
• Microsoft .NET 3.0 and 3.5
• Windows Server 2003, Windows XP, Windows Vista, and Windows 2008

To resolve this issue, specify the following service behavior by adding these settings to the web.config file. Replace <name> with the behavior name of the WCF service.

<serviceBehaviors>
     <behavior name="<name>">
          <useRequestHeadersForMetadataAddress>
               <defaultPorts>
                    <add scheme="http" port="81" />
                    <add scheme="https" port="444" />
               </defaultPorts>
          </useRequestHeadersForMetadataAddress>
     </behavior>
</serviceBehaviors>
        

For more information, see this Microsoft article.

HTTP error 404.17 or 404.3

When you attempt to reach one of the service endpoints from a server hosting the Relativity.Services, you receive an HTTP 404.17 or 404.3 errors.

The error is caused by WCF incorrectly installed, configured, or missing on the server.

Use the following steps to install WCF on machines hosting the Relativity.Services:

1. Open a command prompt on a machine hosting the Relativity.Services.
2. Change to one of the following directories depending on your machine:
   • 64-bit:cd C:\Windows\Microsoft.NET\Framework64\v4.0.30319
   • 32-bit:cd C:\Windows\Microsoft.NET\Framework\v4.0.30319
3. Press Enter.
4. Type ServiceModelReg -I. Press Enter.
5. Repeat steps 1 - 4 on each machine that hosts the Relativity.Services in your environment.

Enable WCF on Windows Server 2012

On Windows Server 2012, you must enable all of the roles under Windows Processing Activation Service to install the WCF Service for .NET.

To install the Windows Process Activation Service:

1. Run Server Manager from the task bar or Start menu.
2. Select Add roles and features.

3. Navigate through the Add Roles and Features Wizard to the server roles selection screen and make sure the Application Server role is selected.

4. Proceed to roles services selection screen and select Windows Process Activation Service.
5. Expand the features under Windows Process Activation Service and select the following features:
   • HTTP Activation
   • Message Queuing (MSMQ) Activation
   • Named Pipe Activation
   • TCP Activation

6. Install the Application Server role.

Incorrect version of .NET enabled for application pools

Since Relativity 7.0 or above only supports .NET Framework v 4.0, you may need to register the .NET version for your environment. Complete these steps:

1. Use the following commands to register the appropriate version of .NET (in Framework64):

     aspnet_regiis -iru -enable

2. Change the application pool to the appropriate version of .NET and recycle the application pool.

   Note: If the application pool fails to restart, restart IIS and then start the application pool again.

Missing handler mappings

Error messages don't provide detailed information for troubleshooting this issue. You will need to compare the handler mappings on the Services API server to those of a known working server. For reference, the following path is used for the handler mapping:

     %SystemRoot%\Microsoft.NET\<framework>\v2.0.50727\aspnet_isapi.dll
        

The <framework> represents Framework or Framework64 directory.

Note: The API on Relativity7 includes handler mappings for .NET 4.0 as well as those for 2.0, using the v4.0.30319 directory.

As illustrated below, these handler mappings may be missing:

• svc-ISAPI-2.0

  

• svc-ISAPI-2.0-64

  

Pipe endpoint could not be found

You will receive the following error message when Net.Pipe is not configured:

System.IO.PipeException: The pipe endpoint 'net.pipe://my-server.kcura.corp/Relativity.Services/AuthenticationNetHTTP.svc' could not be found on your local machine.

This error indicates that no endpoint was listening at Net.Pipe, which can be caused by an incorrect address or SOAP action. You may see this error in the Relativity error log depending on where the call to the Services API was made.

System.ServiceModel.ExceptionDetail Error

You receive the following error message when using the Services API:

Type 'System.ServiceModel.ExceptionDetail' in Assembly 'System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' is not marked as serializable.

For example, you may see this error message when communicating across application domains. If the exception thrown from one domain to another isn't serializable, this error occurs.

Unable to access .svc file path in browser

After you install the Windows Non-HTTP Activation feature, you receive the following error when attempting to access a .svc file path in the web browser:

Could not load type ‘System.ServiceModel.Activation.HttpModule’ from assembly ‘System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089’

To resolve this issue, execute the following command line statement:

     aspnet_regiis.exe /iru
        

Unable to access website

You will be unable to access your website if the HTTP or HTTPS host header references your local machine name. You can update the HTTP or HTTPS host header and reset the ISS to resolve this issue.

Note: Reset IIS during off-hours.

Error occurs when machines in a workgroup attempt to log in

If you receive an error when machines that are part of a workgroup attempt to log in to the Services API, you need to synchronize your client and server clocks. (Machines on the domain are already synchronized with the server.) By default, clock synchronization has a 5 minute range. For information about synchronizing client and server clocks, see this Microsoft article.

Update the HTTP host header

If your scheme is HTTP, use the following steps to update the host header:

1. On the web server, log on as a member of the Administrators group.
2. Open IIS Manager.
3. Under the Sites node, select your website.
4. In the Actions pane, click Bindings to display the Site Bindings.
5. Select HTTP, and click Edit.
6. Update the Host Header on the dialog.
7. Reset IIS.
8. Try to connect.
9. Repeat step 1 -9 on all servers that host Relativity.Services.